Utiliser l’ouitl de documentation sphinx

La documentation officelle de Sphinx-doc

la documentation

des ressources pour sphinx

Des liens pour la syntaxe

université de Grenoble ou

la syntaxe rest. ou

des informations avancées

des ajouter script js

Préparation de l’environnement sphinx

Mise en place en dur …(non recommandé)

mkdir virtualenv
python3 -m venv virtualenv
source virtualenv/bin/activate
#derriere un proxy non configure dans le système
pip install --proxy http://10.255.5.210:3128  install sphinx
# ajouter -U pour les upgrade
#Pour la documentation automatique des modules python
pip install --proxy http://10.255.5.210:3128  sphinx-autodoc
pip install --proxy http://10.255.5.210:3128  flask
apt install mariadb-server
pip install --proxy http://10.255.5.210:3128  -U setup-tools
apt install python3-mysqldb pkg-config #eventuellement mariadb-dev mariadb-dev-compat

pip install --proxy http://10.255.5.210:3128  mysql
    pip install mysql-connector-python
apt install python3-flask
    apt install python3-setuptools
    apt install python3-xmltodict
    #apt install python3-cas
    apt install python3-wtforms

    #pour latex
apt install texlive-latex-recommended
apt install texlive-fonts-recommended
    apt install tex-gyre
    apt install texlive-latex-extra
    apt install latexmk
    #plus ...

# texlive-lang-cyrillic for Cyrillic (and also then cm-super if using the default fonts),

#texlive-lang-greek for Greek (and also then cm-super if using the default fonts),

#texlive-xetex if latex_engine is “xelatex”,

#texlive-luatex if latex_engine is “lualatex”,

#fonts-freefont-otf if latex_engine is either “xelatex” or “lualatex”.

Création d’une documentation sphinx

sphinx-quickstart activites-pedagogiques
vim activites-pedagogiques/sources/index.rst
cd activites-pedagogiques
make html

ajouter l’auto-analyses d’un module:

  • Dans conf.py:

    import os
#chemin contenant le ou les modules
sys.path.insert(0,os.path.abspath('/var/www/serveur/'))

extensions = [
        'sphinx.ext.autodoc',
]

  • Dans un fichier rst :

    Submodules
----------

Module activités
----------------

.. automodule:: blueprints.Activites.Activites
:members:
:undoc-members:
:show-inheritance:


Module Activites BDD:
---------------------

.. automodule:: blueprints.Activites.ActivitesBDD
:members:
:undoc-members:
:show-inheritance:

Utiliser une variable

  • Commencer par installer l’extension

    pip install Sphinx-Substitution-Extensions

  • Dans le conf.py (il y a certainement mieux !)

    mon_appli = 'serveur'
rst_prolog = """
.. |mon_appli| replace:: serveur
"""

sys.path.insert(0,os.path.abspath('/var/www/'+mon_appli+'/'))



extensions = [
        'sphinx.ext.autodoc',
'sphinx_substitution_extensions',
        ../..
]

  • Dans un fichier rst , par exemple usagebdservice.rst

    Utiliser |mon_appli|
====================

    Affichera Utiliser serveur

Dans un code block

echo "serveur une appli pedagogique"

Inline :substitution-code:

echo "serveur informations générales "

substitution-download