<?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="fr">

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

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Charles Monzat</mal:name>
      <mal:email>charles.monzat@free.fr</mal:email>
      <mal:years>2018, 2021</mal:years>
    </mal:credit>
  </info>

<title>Installation des documentations d’API</title>

<synopsis>
  <p>La méthode utilisée par <app>Devhelp</app> pour trouver les documentations d’API.</p>
</synopsis>

<links type="section"/>

<section id="book-format">
  <title>Format de livre</title>
  <p>Consultez <link xref="book-format"/> pour obtenir des informations sur le format de documentation des API que <app>Devhelp</app> reconnaît.</p>
</section>

<section id="books-locations">
  <title>Emplacements des livres</title>
  <p>Dès lors qu’un livre suit le bon format, son répertoire doit être installé à un emplacement dans lequel <app>Devhelp</app> peut le trouver.</p>
  <p><app>Devhelp</app> utilise les <link href="https://specifications.freedesktop.org/basedir-spec/latest/">caractéristiques du répertoire de base de XDG</link> pour trouver les livres. Voici la liste des emplacements recherché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>Notez que les deux derniers sont constitués de listes de répertoires à rechercher. Les valeurs de répertoire sont séparées par des caractères <code>:</code> (deux-points). Ces variables d’environnement sont normalement configurées par l’environnement de bureau ou la distribution.</p>
  <p>Exemples d’emplacements de fichiers de sommaire avec <code>$XDG_DATA_HOME</code> sur un système typique :</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 <app>Devhelp</app> est lancé avec <link href="https://flatpak.org/">Flatpak</link>.</p></item>
  </list>
  <p>Exemple d’emplacement d’un fichier de sommaire avec <code>$XDG_DATA_DIRS</code> sur un système typique :</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> est un outil qui permet de générer une documentation d’API à partir des commentaires ajoutés au code C. Il est utilisé par les bibliothèques et applications GLib, GTK et GNOME.</p>
  <p>GTK-Doc installe les références d’API d’un module dans :</p>
  <p its:translate="no">
    <code>$datadir/gtk-doc/html/$module_name/</code>
  </p>
  <p>Il suit le format de livre pris en charge par <app>Devhelp</app>. Ainsi, en utilisant GTK-Doc, les références d’API peuvent être parcourues dans <app>Devhelp</app> automatiquement (une fois installée au bon endroit).</p>
</section>
</page>
