gwift-book/source/part-1-workspace/documentation.adoc

Documentation

Documentation: be obsessed!

On en a déjà parlé plus haut, il existe un standard en Python pour la définition de la documentation du code: RST (et par extension, Sphinx, qui est le représentatn de facto pour la récupération du code d’une application et sa présentation dans un format souhaité: HTML, ePub, Latex, PDF, …​).

Plusieurs modules de documentation existent, mais nous allons nous concentrer sur Sphinx, qui semble être le plus complet et qui permet d’héberger directement sa documentation sur `ReadTheDocs.org <https://readthedocs.org/>`_. Nous allons également faire en sorte que cette documentation soit compatible avec Django, puisque c’est le but de notre projet.

Sphinx

Commencez par installer Sphinx et ajoutez le dans le fichier requirements/base.txt. A priori, il n’est pas nécessaire de spécifier une version: Sphinx est un outil périphérique, qui ne dépendra pas des autres librairies. Une fois que ce sera fait, exécutez la commande sphinx-quickstart, afin d’initier la documentation pour notre projet:

1. code-block:: shell

   $ sphinx-quickstart.exe
   Welcome to the Sphinx 1.3.3 quickstart utility.

   Please enter values for the following settings (just press Enter to
   accept a default value, if one is given in brackets).

   Enter the root path for documentation.
   > Root path for the documentation [.]: ./docs
   > Separate source and build directories (y/n) [n]: n
   > Name prefix for templates and static dir [_]: _
   > Project name: Gwift
   > Author name(s): Fred & Ced
   > Project version: 0.1
   > Project release [0.1]:
   > Project language [en]: fr
   > Source file suffix [.rst]: .rst
   > Name of your master document (without suffix) [index]:
   > Do you want to use the epub builder (y/n) [n]: n
   Please indicate if you want to use one of the following Sphinx extensions:
   > autodoc: automatically insert docstrings from modules (y/n) [n]: y
   > doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
   > intersphinx: link between Sphinx documentation of different projects (y/n) [n] n
   > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
   > coverage: checks for documentation coverage (y/n) [n]: y
   > pngmath: include math, rendered as PNG images (y/n) [n]: n
   > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n
   > ifconfig: conditional inclusion of content based on config values (y/n) [n]: n
   > viewcode: include links to the source code of documented Python objects (y/n) [n]: y
   > Create Makefile? (y/n) [y]: y
   > Create Windows command file? (y/n) [y]: y

   Creating file ./docs\conf.py.
   Creating file ./docs\index.rst.
   Creating file ./docs\Makefile.
   Creating file ./docs\make.bat.

   Finished: An initial directory structure has been created.

Deux-trois petites choses à modifier pour que Sphinx puisse intéragir avec Django. Ouvrez le fichier docs/conf.py et modifier ou ajoutez les variables suivantes:

1. code-block:: python

   # docs/conf.py

   sys.path.insert(0, os.path.abspath('../gwift'))
   sys.path.insert(0, os.path.abspath('.'))

   from django.conf import settings
   settings.configure()

   html_theme = 'sphinx_rtd_theme'

De cette manière, on modifie le thème utilisé lors de la génération des pages HTML, en remplaçant le thème Alabaster par le thème ReadTheDocs, on demande à Sphinx d’initier l’environnement Django existant, et on lui demande également d’aller chercher les informations dans le répertoire courant, mais également dans le répertoire ../gwift. Sans cela, les références que l’on fera dans la documentation ne seront pas récupérées.