1. Maintenance de la documentation

1.1. Fonctionnement de la chaîne d’édition

Note

Cette documentation est générée et hébergée par le site « Read the Docs », qui permet sa mise à jour en continu, avec notamment les caractéristiques suivantes:

• un système de recherche intégré
• une édition simplifiée
• une mise en forme structurée et rigide (idéale pour des documents techniques)
• une gestion de plusieurs versions
• une édition en plusieurs langues

• Les fichiers sources sont stockés dans un répertoire de Github.com.
• Ils sont écrits en language reStructuredText (extension .rst).
• Un webhook est établi entre « Read the Docs » et les fichiers sources sous Github.com.
• A chaque changement d’un fichier source, le webhook active la régénéraion du site en ligne.

1.2. Prérequis

• Disposer d’une compte chez Github.com (ou similaire)
• Disposer d’un compte chez « Read the Docs » connecté aux sources du compte Github.com.

1.2.1. Compléments

Afin d’assurer un meilleur confort d’édition, les logiciels ci-après peuvent être installés en complément :

• Un éditeur de code (Visual Studio Code dans notre cas)
• Le moteur d’édition Sphinx, qui est le moteur de génération de « Read the Docs ».

1.3. Mise en place d’une nouvelle documentation

• Sous Github.com

  • Créer un repository sous Github.com
  • relever l’URL de celui-ci.

• Sous Read the Docs

  • Cliquer Import a Project et sélectionner un Repository
  • Cliquer Admin > Settings. Vérifier l’URL du champ « Repository URL ».
  • Adapter les autres champs en fonction du besoin, notamment l’édition au format PDF ou ePub, en plus de HTML
  • Cliquer Admin > Settings > Advanced Settings. Vérifier le niveau de confidentialité sous « Privacy Level ».

  Note

  Cette installation minimale permet déjà de créer une documentation en ligne en éditant des fichier .rst directement sous Github.com.

  Ceci constitue toutefois une solution peu élégante. D’autre part, le résultat de la conversion des fichiers .rst vers html par « Read the Docs » est assez lente.

  Afin de travailler dans de meilleures conditions, nous allons procéder en complément à l’installation d’un éditeur de code connecté à Github.com, ainsi qu’à l’installation du moteur de génération de documentation Sphinx (qui est identique à celui de « Read the Docs »).

1.4. Installation du système pour l’édition locale

• Installation du moteur Sphinx

  Note

  Sphinx a besoin de Python pour fonctionner. Sous Windows, l’installation de Anaconda constitue probablement l’option la plus simple.

  • Télécharger et installer Anaconda

  • Ouvrir la console « Anaconda Prompt »

    conda install sphinx    # Installation de Sphinx
    

    Pour générer un nouveau projet :

    cd /path/to/project/
    mkdir docs
    cd docs
    sphinx-quickstart
    # Répondre aux questions en validant les valeurs proposée en cas de doute, il est possible de reconfigurer le projet ultérieurement.
    # Vous obtiendrez un fichier de configuration de base conf.py et
    # un document d'index basique, mais fonctionnel et prêt à être édité.
    

    Pour générer le site html à partir des sources existantes :

    # pour générer les documents en html :
    cd /path/to/project/docs
    make html
    # un dossier _build existe dorénavant, avec les fichiers sources du site html
    # vous pouvez consulter le site généré en local sous 'file:///path/to/project/docs/_build/html/index.html
    

    Optionnel : pour automatiser la régénération de la documentation html à chaque modification d’un fichier source :

    # installer les modules nécessaires
    conda install -c conda-forge sphinx-autobuild
    # se déplacer dans le répertoire de la documentation
    cd /path/to/project/docs
    # initialiser la régénération automatique
    sphinx-autobuild . _build/html
    # Dès maintenant, la documentation est disponible en local à l'adresse http://localhost:8000.
    # il suffit de raffraîchir la page du navigateur (CTRL+F5) pour oubtenir la nouvelle version
    # après quelques secondes.
    #
    # interrompre cet automatisme avec CTRL+C
    

• Sous Visual Studio Code

  • Installer le contrôle de code source git au besoin

  • Créer un répertoire pour les documents de projet en local

  • Initialiser le répertoire pour git.

  • Connecter le git local au git distant

    cd /home/myProject/
    git remote add origin https://...
    git remote show origin # if everything is ok, you will see your remote
    git push -u origin master # assuming your are on the master branch.
    

Avertissement

Ne pas oublier de pousser les modifications régulièrement vers Github.com, sans quoi le site online ne sera pas mis à jour.