README du projet de documentation utilisateur de Nextcloud pour la DirCom

| Author | DirCom (MOY 1666, CNRS) |

Introduction

Le présent projet a pour but de documenter l’usage de Nextcloud pour les utilisateurs de la DirCom. Pour un non-contributeur au présent projet, les répertoires d’intérêt sont les suivants:

  • html/: documentation au format HTML (site web statique complet)

  • pdf/: documentation au format PDF.

Formats et outils

Les documentations HTML et PDF sont générées par l’outil de documentation Sphinx, qu’on aura pris soin d’installer par ailleurs pour contribuer au projet (cf. section suivante). Les sources de la documentation sont disponibles dans le répertoire src/, au format reStructuredText que comprend Sphinx: ce sont des simples fichiers texte.

Les figures sont majoritairement créées avec l’outil Diagrams.net au format PNG et enregistrées dans le répertoire src/figures/. Elles peuvent être composées d’éléments plus petits et réutilisable inter-figures, souvent alors des images au format SVG éditables par Inkscape.

La génération des sorties HTML et PDF est commandée par le Makefileà la racine du projet. Sous Windows, un tel outil peut se trouver via une image de distribution Linux par Windows Subsystem Linux.

Dépendances du projet de documentation

La génération des sorties HTML et PDF du présent projet de documentation se fait grâce à la série de logiciels tiers spécifiés dans le fichier pip-requirements.txt.

On pourra les installer dans un virtualenv créé pour l’occasion. Sous Unix, cela peut se faire par exemple avec:

# Set where your new virtualenv will stand
$ VENV="/opt/virtualenvs/sphinx"
# Create it, with 'venv' Python3 built-in module
$ python3 -m venv "${VENV}"
# Update packaging libraries
$ "${VENV}/bin/python" -m pip install --upgrade setuptools
$ "${VENV}/bin/python" -m pip install --upgrade pip
$ "${VENV}/bin/python" -m pip install --upgrade wheel
# Install project's dependencies
$ "${VENV}/bin/python" -m pip install -r pip-requirements.txt

Pour Windows, les commandes sont assez similaires, à la variation près que l’exécutable python.exe se situe dans le répertoire Scripts/ du virtualenv. Également, il faut rajouter l’installation de dépendances additionnelles propres, listées dans le fichier pip-requirements-windows.txt:

REM New virtualenv was previously created in
REM "C:\Users\vincent.ferotin\local\virtualenvs\Sphinx" directory.
C:\Users\vincent.ferotin\local\virtualenvs\Sphinx\Scripts\python.exe -m pip install -r pip-requirements-windows.txt

Développement de la documentation et génération des sorties HTML & PDF

Le projet offre, à travers son Makefile, les tâches les plus courantes. Vous pouvez les lister en invoquant (GNU) make sans argument, ce qui affichera son aide succinte intégrée, notamment la liste des cibles (ici des « commandes ») offertes.

Une opération courante, par exemple html pour générer la sortie HTML, s’invoquera en spécifiant à make cette cible particulière comme argument:

$ make html

La génération du PDF se fait avec la cible pdf, et la re-génération de toutes par la cible all.

Structure détaillée du projet

La documentation du projet est composée de matériel pour Sphinx et rinohtype, et des utilisateurs n’utilisant aucun de ces deux outils:

  • le matériel pour Sphinx et rinohtype comprend:

    • le fichier Makefile, qui contient les cibles pour générer les différents formats de sortie (HTML & PDF),

    • le répertoire src/, qui comprend les sources reStructuredText et la configuration nécessaires à Sphinx pour générer les différents formats de sortie,

    • les figures intégrées à la documentation se trouvent dans le sous-répertoire src/figures/, et créées par l’outil Diagrams.net,

    • des images comme les logos ou servant de briques pour les figures sont enregistrées dans le sous-répertoire src/img/,

    • le répertoire doctrees/, utilisé en interne par Sphinx,

    • le répertoire rinoh/, utilisé en interne par rinohtype,

  • les sorties HTML et PDF, utilisables par les lecteurs du projet, sont enregistrées respectivement dans les répertoires html/ et pdf/.

Cette structure, cette arborescence permet donc d’enregistrer et versionner tant les sources de la documentation, ses formats de sortie, et la configuration de la machine virtuelle permettant la transformation des premières en ces secondes, et autorisant des utilisateurs non techniciens à accéder néanmoins au contenu de la documentation – pourvu bien sûr qu’on prenne soin de systématiquement générer et versionner les sorties HTML et PDF à chaque modification des sources.

Utilisation

Maintenant que la configuration requise a été réalisée, il est facile d’utiliser le virtualenv pour demander à Sphinx et rinohtype de générer les sorties HTML et PDF.

Les cibles principales du Makefile sont listées dans la sortie de help:

$ make help

Il est possible d’enchaîner les cibles, pour réaliser l’exécution de plusieurs recettes en une même invocation. Le patron d’invocation est le suivant:

$ make TARGET1 [TARGET2 [...]]

Pour regénérer l’intégralité des sorties, utiliser la cible all, en surchargeant au besoin la variable d’environnement SPHINXBUILD pour pointer le chemin de l’exécutable sphinx-build du virtualenv précédemment créé:

$ SPHINXBUILD="$VENV/bin/sphinx-build" make all