Documentation Sphinx

Généralités

http://www.sphinx-doc.org/en/master/

Il faut:

On peut générer conf.py en utilisant la commande: sphinx-quickstart. Il faut ensuite l’éditer.

Sphinx / RestructuredText permet comme pas mal de langages de Markup, de faire des documents assez facilement, avec des titres à plusieurs niveaux, des liens http externes, des liens et références internes etc.

On peut utiliser des styles, qu’on choisit dans le fichier de conf, et qu’on peut customiser par des CSS.

Sphinx ajoute le parsing de code source python et permet de faire la doc de modules, classes, fonctions python. Il a aussi des extensions.

autodoc, peut-être la plus importante, permet le parsing automatique des modules / classes python.

Il y a d’autres extensions pour les liens (références croisées) entre docs sphinx et les classes documentées (intersphinx), des galleries d’images et de sniplets de code (sphinx-gallery), pour documenter facilement et lisiblement les paramètres des fonctions (napoleon ou numpydoc), etc etc.

Ex de lien sur un autre document: Doc de modules python

Générer le HTML

Si on a généré un Makefile avec sphinx-quickstart, il suffit de faire:

make html

dans le bon directory (doc/ ici).

Sinon on peut le faire à la main:

sphinx-build . _build/html

Code python

Ex de bloc de code python:

from capsul.api import capsul_engine

ce = capsul_engine()
process = ce.get_process_instance(
    'capsul.pipeline.test.test_activation.MyPipeline'

On peut évidemment faire des liens sur des sample_module.mod1.Class1 du projet (nom “long”), ou avec un nom “court”: Class1, ou sous un autre nom.

Avec intersphinx on peut aussi faire des liens sur les classes / foonctions / modules d’autres projets: argparse.ArgumentParser, capsul.pipeline.pipeline.Pipeline.

Ou des liens sur des pages de projets externes avec extlinks.

Notebooks

nbsphinx peut convertir des notebooks jupyter en docs sphinx, consultables dans la doc. Ça nécessite un peu de config et préprocessing pour vraiment bien s’intégrer.

Le préprocessing a été ajouté à conf.py qui est exécuté automatiquement à chaque build de doc. Il sert à:

  • convertir le notebook avec le bon noyau python (python2 / python3)

  • copier le notebook “brut” dans la doc construite de manière à être téléchargeable aussi, pas seulement en version convertie en sphinx.

  • copier les images qui vont avec le notebook dans la doc construite.

Ça nécessite d’avoir aussi installé pandoc.

Traitements et pipelines Capsul

On peut générer de la doc Sphinx pour les process et pipelines Capsul, en utilisant capsul.sphinxext.capsul_pipeline_rst.

Capsul

La commande adéquate peut être ajoutée dans conf.py. Ça revient à lancer la commande:

python -m capsul.sphinxext.capsul_pipeline_rst -i sample_module.capsul -o _build/html/process_docs/example_module --schema

Intégration à github gh-pages via Travis-ci

La doc peut être construite par Travis-CI et injectée dans la branche gh-pages du projet GitHub.

Pour cela il faut:

  • donner les droits à travis-ci de pousser la doc dans le projet github (la branche gh-pages est sous git). Pour cela il faut générer un “github personal access token”, et le mettre en variable d’environnement dans le build travis-ci (ici c’est GITHUB_ACCESS_TOKEN). La doc est ici.

  • avoir créé sur GitHub la branche gh-pages (vide, possiblement détachée).

  • configurer .travis.yaml, en ajoutant un truc de ce genre (la condition ici est liée à des variables définies plus tôt dans .travis.yaml, il faut l’adapter):

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_ACCESS_TOKEN
  target-branch: gh-pages
  local-dir: doc/_build/html
  on:
    branch: master
    condition: $PUSH_DOC_TO_GH_PAGES == yes && $TRAVIS_OS_NAME == linux && $TRAVIS_PYTHON_VERSION == 3.5