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/
etpdf/
.
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