<!--
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">

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

<title>Installing API documentation</title>

<synopsis>
  <p>How <app>Devhelp</app> finds the API documentation.</p>
</synopsis>

<links type="section" />

<section id="book-format">
  <title>Book format</title>
  <p>
    See <link xref="book-format" /> for information on the API documentation
    format that <app>Devhelp</app> recognizes.
  </p>
</section>

<section id="books-locations">
  <title>Books locations</title>
  <p>
    Once a book follows the right format, its directory needs to be installed
    at a location where <app>Devhelp</app> will find it.
  </p>
  <p>
    <app>Devhelp</app> uses the
    <link href="https://specifications.freedesktop.org/basedir-spec/latest/">XDG Base Directory Specification</link>
    to find the books. The list of locations searched is:
  </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>
    Note that the two latter consist of lists of directories to look for.
    Directory values are separated by <code>:</code> characters. Those
    environment variables are normally set up by the desktop environment or
    distribution.
  </p>
  <p>
    Examples of locations to index files with <code>$XDG_DATA_HOME</code> on a
    typical system:
  </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>
      if <app>Devhelp</app> is launched with
      <link href="https://flatpak.org/">Flatpak</link>.
    </p></item>
  </list>
  <p>
    Example of a location to an index file with <code>$XDG_DATA_DIRS</code> on
    a typical system:
  </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>
    GTK-Doc installs the API reference of a module into:
  </p>
  <p its:translate="no">
    <code>$datadir/gtk-doc/html/$module_name/</code>
  </p>
  <p>
    It follows the book format supported by <app>Devhelp</app>. So by using
    GTK-Doc, the API reference can be browsed in <app>Devhelp</app>
    automatically (once installed in the right location, that is).
  </p>
</section>
</page>
