Documentation_Automatique ¶

DocUtils ¶

Liens WEB:

Page d’accueil du projet [1]

Docutils is an open-source text processing system for processing plaintext documentation into useful formats, such as HTML, LaTeX, man-pages, open-document or XML. It includes reStructuredText, the easy to read, easy to use, what-you-see-is-what-you-get plaintext markup language.

reStructuredText (.rst)¶

Liens WEB:

reStructuredText est un langage de balisage léger utilisé notamment dans la documentation du langage Python.

Bien que sauvegardé sous un format textuel, l’extension associée est parfois indiquée comme étant RST. L’analyseur syntaxique de référence est implémenté comme élément Docutils du cadre d’application du langage de programmation Python, mais d’autres implémentations existent par ailleurs (par exemple Pandoc en Haskell ou JRst en Java).

reStructuredText permet d’exporter dans notamment les formats HTML, XML, LaTeX, ODF.

Directives ¶

Insérez du code html ¶

.. raw:: html

   <br>
   # Attention, il faut sauter une ligne entre 'raw' et le code html

Insérer une image ¶

.. image:: [chemin/vers/une/image]
   :align: center

ex:
.. image:: ./Images/monImage.jpg
   :align: center

# Important : les chemins doivent être renseigné avec des '/' même sous windows

Directive TODO ¶

Liens_Web:

Doc Sphinx [11]

.. todo::

   blablabla

N.B : il existe la directive « .. todolist:: », mais elle ne semble pas / plus fonctionner. Préférez la directive « .. todo:: » sous forme de liste commençant avec des puces.

ex:

.. todo::

   * bla

   * ble

   * bli

Utiliser la directive TODO avec Sphinx ¶

Dans “conf.py” :

extensions = ['sphinx.ext.todo']

...

todo_include_todos = True

Insérer des formules mathématiques ¶

Liens_Web:

Les formules mathématiques doivent respecter la syntax LaTeX. Il y a 2 types d’insertion des formules :

La formule occupe une ligne pour elle toute seule

La formule est intégrée dans une ligne (inline)

Utilisation de la directive “math” dans Sphinx ¶

Dans “conf.py”, il faut ajouter un éléments dans “extensions” :

extensions = ['sphinx.ext.mathjax']

Équation sur une seule ligne ¶

.. math::

  \frac{ \sum_{t=0}^{N}f(t,k) }{N}
Aperçu:

Penser à sauter une ligne vide avant la directive et après la formule

\[\frac{ \sum_{t=0}^{N}f(t,k) }{N}\]

Équation intégrée dans la ligne ¶

blablabla :math:`\frac{ \sum_{t=0}^{N}f(t,k) }{N}` encore du blablabla
Aperçu:

La formule doit être entourée par « ` » (ALTgr-7)

Voici une super équation : $\frac{ \sum_{t=0}^{N}f(t,k) }{N}$

Sphinx ¶

Liens WEB:

Installer Sphinx ¶

pip install sphinx

Démarrage et initialisation rapide ¶

sphinx-quickstart

Rédiger et publier de la doc avec Sphinx sur GitHub-pages ¶

Préparation de l’arborescence ¶

Création de 2 sous dossier à la racine du projet
    fakeLib
        project
        webDoc

**N.B** : 'arboProject' inclue la création de ses 2 dossiers
Lier le dépôt local (Git) au dépôt distant (GitHub)
git remote add origin https://github.com/[votre_nom_sous_github]/[votre_depot_github]
git push -u origin master
Initialiser Sphinx
Ce placer dans le dossier _1_userDoc (pensez à supprimer le suffixe « _v » et ouvrir une invite de commande.
Exécuter la commande :
sphinx-quickstart
Il faut accepter la plupart des choix par défaut sauf pour 4 d’entre eux :
Separate source and build directories (y/n) [n]:y
Project language [en]: fr
autodoc: automatically insert docstrings from modules (y/n) [n]: y
githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: y
Configurer “conf.py”
Repérez les 3 lignes :
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
Remplacez les par :
import os
import sys
sys.path.insert(0, os.path.abspath('../../'))
Puis la ligne :
exclude_patterns = []
A remplacer par :
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
Configurer “Makefile”
Repérez les 2 lignes :
SOURCEDIR = source
BUILDDIR = build
Remplacez les par :
SOURCEDIR = .
# Attention, il y a un point après le égal.
# Cela signifie : "répertoire courant"

BUILDDIR = ../../webDoc
Configurer “Make.bat”
Rechercher la ligne :
set BUILDDIR=build
A remplacer par :
set BUILDDIR= ..\..\webDoc
Faire un commit et le pousser dans le dépôt distant
git add .
git commit -m "install et conf de Sphinx"
git push -–all
Création de la branch “gh-pages”
Copier l’url du dépôt distant

Se placer dans le dossier “webDoc”
Cloner le dépôt distant dans “html” et se déplacer dans se dossier
git clone [url_copiée_depuis_GitHub] html
# Attention, html est en minuscule.

cd html
Création de la branch local “gh-pages”
git branch gh-pages
Création d’un lien symbolique entre notre nouvelle branch et une branch homonymes dans notre dépôt distant puis on bascule automatiquement sur cette nouvelle branch
git symbolic-ref HEAD refs/heads/gh-pages
Suppression de l’indexation existante de notre nouvelle branch
del .git\index
on nettoie le contenue de notre nouvelle branch pour ne pas refaire un commit sur les éléments de la branch principale
git clean -fdx
Préparation des éléments à intégrer dans notre documentation
Rappel:

L’ordre dans lequel nous renseignons les fichiers, correspond à l’ordre dans lequel ils seront afficher sous GitHub.

le fichier « index.rst » ne prend pas en charge les chemin relatif
Création du fichier “includeMe.rst”
Créer, dans le même dossier que le fichier “index.rst”, le fichier “includeMe.rst”.
Renseigner le fichier de la façon suivante :
======================
README_[nom_du_projet]
======================

.. include:: ../../README.rst
Ajouter l’entrée “includeMe” dans “index.rst”
Extraction de la documentation depuis les docString du code
Créer, dans le même dossier que le fichier “index.rst”, un fichier ayant un nom significatif qui permette de se référer au code :
ex :
fakeLib
Renseigner se nouveau fichier sous la forme :
 fakeLib
 =======

 .. automodule:: _3_software.fakeLib
    :members:

# Ne pas oublier les 3 espaces devant ':members:'
Ajouter l’entrée “fakeLib” dans “index.rst”
Génération de la doc et MAJ de la branch master en local et distant :
make html
# si tous se passe bien, on obtien le message suivant :
# "Build finished. The HTML pages are in ..\..\webDoc\html."
cd ..
git add .
git commit -m "blabla"
git push orgin master
# on pousse la branch 'master' sur le dépôt distant
MAJ de la branch gh-pages en local et en distant :
cd ..\..
cd webDoc\html
git branch
# on vérifie que l'on est bien sur la branch 'gh-pages'
git add .
git commit -m "MAJ de la doc"
git push origin gh-pages
# on pousse la branch 'gh-pages' sur le dépôt distant
Accéder à la documentation publiée sur GitHub :
Nous pouvons à présent consulter notre jolie documentation en ligne à l’adresse : https://<utilisateur_Gihub>.github.io/[nom_du_dépot]/

Exemple :
https://poltergeist42.github.io/fakeLib/
Mettre à jour automatiquement la branch “gh-pages” et le dépôt distant
Pour automatiser la MAJ de “gh-pages” il faut modifier le fichier “Makefile” et “make.bat”.
Dans “Makefile”, se placer à la fin du document et ajouter les lignes suivantes à la fin du document :
# reconstruction de la branch "gh-pages" et mise a jour du depot distant
buildandcommithtml: html

    cd $(BUILDDIR)/html; git add . ; git commit -m "rebuilt docs"; git push origin gh-pages
Dans “make.bat” repérer les 2 lignes :
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
Intercaler les lignes suivantes entre les 2 :
rem reconstruction de la branch "gh-pages" et mise a jour du dépôt distant
cd %BUILDDIR%\html
git add .
git commit -m "rebuilt docs"
git push origin gh-pages
Cloner un dépôt distant utilisant “gh-pages”
Depuis la racine du projet cloner le dépôt distant dans 2 dossiers ayant la même arborescence que le projet initial :
ex :
D:\fakeLib>
> git clone https://github.com/poltergeist42/fakeLib.git .\project
> git clone https://github.com/poltergeist42/fakeLib.git .\webDoc\html
Ce déplacer dans le dossier “html” et vérifier la branch courante. Il ne devrait y avoir que la branch “master”
cd .\webDoc\html
git branch
Recréer la branch locale “gh-pages” et l’associer avec le dépôt distant
git checkout -b gh-pages remotes/origin/gh-pages
Une nouvelle vérification des branch locale devrait nous indiquer qu’il y a 2 branch et que nous sommes sur la branch “gh-pages”