<?xml version="1.0" encoding="utf-8"?>
<!--
SPDX-FileCopyrightText: 2019 Sébastien Wilmet <swilmet@gnome.org>
SPDX-License-Identifier: CC-BY-SA-4.0
-->
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="installing-api-documentation" xml:lang="devhelp-ca">

<info>
  <link type="guide" xref="index"/>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Miquel-Àngel Burgos i Fradeja</mal:name>
      <mal:email>miquel.angel.burgos@gmail.com</mal:email>
      <mal:years>2020</mal:years>
    </mal:credit>
  </info>

<title>Instal·lació de documentació d'API</title>

<synopsis>
  <p>Com troba el <app>Devhelp</app> la documentació d'API.</p>
</synopsis>

<links type="section"/>

<section id="book-format">
  <title>Format del llibre</title>
  <p>Vegeu <link xref="book-format"/> per a informació sobre el format de documentació d'API que el <app>Devhelp</app> reconeix.</p>
</section>

<section id="books-locations">
  <title>Ubicacions dels llibres</title>
  <p>Un cop que un llibre té el format correcte, el seu directori s'ha d'instal·lar en una ubicació on el <app>Devhelp</app> pugui trobar-lo.</p>
  <p>El <app>Devhelp</app> utilitza l'<link href="https://specifications.freedesktop.org/basedir-spec/latest/">especificació del directori base XDG</link> per a trobar els llibres. La llista d'ubicacions on se cerca és:</p>
  <list its:translate="no">
    <item><p><code>$XDG_DATA_HOME/devhelp/books/</code></p></item>
    <item><p><code>$XDG_DATA_HOME/gtk-doc/html/</code></p></item>
    <item><p><code>$XDG_DATA_DIRS/devhelp/books/</code></p></item>
    <item><p><code>$XDG_DATA_DIRS/gtk-doc/html/</code></p></item>
  </list>
  <p>Tingueu en compte que les dues darreres consisteixen en llistes de directoris on cercar. Els directoris se separen amb el caràcter <code>:</code>. Aquestes variables d'entorn solen venir configurades per l'entorn d'escriptori o la distribució.</p>
  <p>Exemple d'ubicacions de fitxers d'índex amb <code>$XDG_DATA_HOME</code> en un sistema típic:</p>
  <list>
    <item its:translate="no"><p>
      <file>~/.local/share/devhelp/books/glib/glib.devhelp2</file>
    </p></item>
    <item><p><file>~/.var/app/org.gnome.Devhelp/data/devhelp/books/glib/glib.devhelp2</file> si el <app>Devhelp</app> s'inicia amb el <link href="https://flatpak.org/">Flatpak</link>.</p></item>
  </list>
  <p>Exemple d'una ubicació d'un fitxer d'índex amb <code>$XDG_DATA_DIRS</code> en un sistema típic:</p>
  <list>
    <item its:translate="no"><p>
      <file>/usr/share/gtk-doc/html/glib/glib.devhelp2</file>
    </p></item>
  </list>
</section>

<section id="gtk-doc">
  <title>GTK-Doc</title>
  <p>
    <link href="https://gitlab.gnome.org/GNOME/gtk-doc">GTK-Doc</link> is a
    tool to generate API documentation from comments added to C code. It is
    used by GLib, GTK and GNOME libraries and applications.
  </p>
  <p>El GTK-Doc instal·la la referència API d'un mòdul a:</p>
  <p its:translate="no">
    <code>$datadir/gtk-doc/html/$module_name/</code>
  </p>
  <p>Segueix el format de llibre compatible amb el <app>Devhelp</app>. Per tant, mitjançant el GTK-Doc, es pot navegar automàticament per la referència API al <app>Devhelp</app> (un cop instal·lada a la ubicació correcta, és clar).</p>
</section>
</page>
