========================= Documentation_Automatique ========================= .. contents:: :backlinks: top -------- DocUtils -------- :Liens WEB: * `Page d'accueil du projet`_ .. _`Page d'accueil du projet`: http://docutils.sourceforge.net/ 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: * `Références officielles`_ * `Définition Wikipedia`_ * `Exemple et définition en français`_ * `convertir dynamiquement les fichiers ".rst" en page Web`_ * `Pour ajouter la syntaxe "reStructuredText" à notePad++`_ * `Un petit guide de référence`_ * `détail de syntaxe avancé`_ * `Explication détailler des directives (ex : images, include, etc ...)`_ * `Syntaxe avancée`_ .. _`Références officielles`: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html .. _`Définition Wikipedia`: https://fr.wikipedia.org/wiki/ReStructuredText .. _`Exemple et définition en français`: https://aful.org/wikis/interop/ReStructuredText .. _`convertir dynamiquement les fichiers ".rst" en page Web`: https://mg.pov.lt/restview/ .. _`Pour ajouter la syntaxe "reStructuredText" à notePad++`: https://github.com/steenhulthin/reStructuredText_NPP .. _`Un petit guide de référence`: http://docutils.sourceforge.net/docs/user/rst/quickref.html .. _`détail de syntaxe avancé`: http://python.physique.free.fr/aide/Partie1.html .. _`Explication détailler des directives (ex : images, include, etc ...)`: http://docutils.sourceforge.net/docs/ref/rst/directives.html .. _`Syntaxe avancée`: http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html 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
# 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`_ .. _`Doc Sphinx`: http://www.sphinx-doc.org/en/master/usage/extensions/todo.html :: .. 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: * `Convention mathématiques utilisées en LaTeX`_ * `Ensemble des symboles mathématiques, le code unicode et la syntaxe LaTeX`_ * `Explication simple et complète de l'utilisation des instructions mathématiques en LaTeX`_ .. _`Convention mathématiques utilisées en LaTeX`: https://fr.wikibooks.org/wiki/LaTeX/%C3%89crire_des_math%C3%A9matiques .. _`Ensemble des symboles mathématiques, le code unicode et la syntaxe LaTeX`: https://fr.wikipedia.org/wiki/Table_de_symboles_math%C3%A9matiques .. _`Explication simple et complète de l'utilisation des instructions mathématiques en LaTeX`: https://fr.wikibooks.org/wiki/LaTeX/Math%C3%A9matiques 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 .. math:: \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 : :math:`\frac{ \sum_{t=0}^{N}f(t,k) }{N}` #### ------ Sphinx ------ :Liens WEB: * `Tutorial`_ * `un petit cookbook sur la configuration`_ .. _`Tutorial`: http://www.sphinx-doc.org/en/stable/tutorial.html .. _`un petit cookbook sur la configuration`: https://developer.ridgerun.com/wiki/index.php/How_to_generate_sphinx_documentation_for_python_code_running_in_an_embedded_system 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://.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'** Modification de thèmes dans Sphinx ================================== :Liens_Web: * `Doc officiel de Sphinx concernant le changement de thèmes`_ .. _`Doc officiel de Sphinx concernant le changement de thèmes`: http://www.sphinx-doc.org/en/master/theming.html Installer le pack de thèmes pour Sphinx --------------------------------------- :: pip install sphinxjp.themes.dotted Utiliser Sphinx pour traité les données d'autre Générateur de doc ================================================================= Utiliser Sphinx pour traité les données de Doxygen -------------------------------------------------- :Liens_Web: * `Breathe`_ : permet de transformer le XML générer par Doxygen en un contenu exploitable par Sphinx .. _`Breathe`: http://breathe.readthedocs.io/en/latest/ Utiliser Sphinx pour traité les données de JSDOC (Javascript) ------------------------------------------------------------- :Liens_Web: * `Sphinx-js`_ : Dépôt pipy * `Introducing sphinx-js`_ .. _`Sphinx-js`: https://pypi.org/project/sphinx-js/ .. _`Introducing sphinx-js`: https://hacks.mozilla.org/2017/07/introducing-sphinx-js-a-better-way-to-document-large-javascript-projects/ #### ----- JSDOC ----- :Liens_Web: * `JDSOC Wikipedia`_ * `JSDoc : Génération de documentation en Javascript`_ * `JSDOC Github`_ * `Doc apparament officiel`_ (pas sexy du tout) * `Créer des commentaires JSDoc pour IntelliSense JavaScript`_ (Visual Studio) .. _`JDSOC Wikipedia`: https://fr.wikipedia.org/wiki/JSDoc .. _`JSDoc : Génération de documentation en Javascript`: https://www.supinfo.com/articles/single/2818-jsdoc-generation-documentation-javascript .. _`JSDOC Github`: https://github.com/jsdoc/jsdoc .. _`Doc apparament officiel`: https://jsdoc.app/ .. _`Créer des commentaires JSDoc pour IntelliSense JavaScript`: https://docs.microsoft.com/fr-fr/visualstudio/ide/create-jsdoc-comments-for-javascript-intellisense?view=vs-2015 #### -------- Weblinks -------- .. target-notes::