À propos de la documentation de Galette

La documentation de Galette, publiée sous les termes de la licence Attribution-ShareAlike 3.0 Unported, est écrite en reStructuredText et est construite à l’aide du système de documentation Sphinx.

Sphinx permet de construire la documentation dans des formats différents depuis une seule et même source. La documentation de Galette est donc disponible aux formats HTML, PDF et EPUB ; grâc à Read the docs.

Construire la documentation

Tout d’abord, clonez le dépôt, référez-vous à la documentation GIT de Galette pour récupérer les sources.

  • Sphinx pour générer les formats HtML et EPUB,
  • un environnement TeX/LaTeX complelt pour générer le PDF (TeX Live, MacTEx, MikTeX).

Pour construire la documentation, placez vous à la racine du projet (un dossier galettedoc si vous avez cloné le dépôt GIT) puis lancez make``avec le ou les formats souhaités (``html, epub, latex). pour construire la documentation dans ces trois formats, nous lancerions :

$ make html epub latexpdf
  sphinx-build -b html -d build/doctrees  source build/html
  Running Sphinx v1.8.4
  loading translations [fr]... done
  making output directory...
  building [mo]: targets for 0 po files that are out of date
  building [html]: targets for 41 source files that are out of date
  [...]
  Build finished. The HTML pages are in build/html.
  sphinx-build -b epub -d build/doctrees  source build/epub
  Running Sphinx v1.8.4
  loading translations [fr]... done
  making output directory...
  loading pickled environment... done
  building [mo]: targets for 0 po files that are out of date
  building [epub]: targets for 41 source files that are out of date
  [...]
  Build finished. The epub file is in build/epub.
  sphinx-build -b latex -d build/doctrees  source build/latex
  Running Sphinx v1.8.4
  loading translations [fr]... done
  making output directory...
  loading pickled environment... done
  building [mo]: targets for 0 po files that are out of date
  building [latex]: all documents
  [...]
  Running LaTeX files through pdflatex...
  [...]
  pdflatex finished; the PDF files are in build/latex.

Traductions

Pour mettre à jour les traductions, il est nécessaire de mettre à jour les fichiers POT depuis les fichiers source rst. Pour cela, vous lancerez la commande suivante :

$ sphinx-build -b gettext source source/locale

Pour tester vos modifications sur votre poste de travail, vous devrez compiler la documentation en utilisant des paramètres complémentaires à la commande make. Par exemple, pour construire la documentation en HTML en français, lancez :

$ make -e SPHINXOPTS="-D language='fr'" html

Note

Par défaut, la commande make compilera la documentation en anglais.

Comment contribuer ?

Un gestionnaire de bogues dédié à la documentation vous permet de nous informer des problèmes que vous pourriez trouver et nous soumettre des correctifs ou des évolutions que vous souhaiteriez voir intégrées au projet.

Toutes les contributions à la documentation doivent suivre les règles de contribution au code source de Galette.