Génération de documentation en intégration continue avec Sphinx

Prérequis

Git \& instance gitlab

* Je pars du principe que les bases de Git sont connues ;
* Personnellement, j’utilise Framagit. Vous pouvez utiliser n’importe-quelle autre instance, du moment qu’elle permet la création de page.

Sphinx

Sphinx est un logiciel de génération automatique de documentation.
Voir la page [sphinx] pour voir comment l’installer et l’utiliser localement avec votre projet (c’est toujours mieux de faire du débug de oc localement).
Je pars du principe que vous avez déjà généré localement vos fichiers et que dans votre répertoire, il y a une arborescence du type :

docs
├── build
│   ├── doctrees
│   │   └── ...
│   └── html
│       └── ...
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── conf.py~
    ├── index.rst
    ├── index.rst~
    ├── parserhtml.rst~
    ├── _static
    └── _templates

Démarrage

Initialisation du git pour la documentation

* Les fichiers source, avant la documentation sont sur le git et tout est propre
* Éditer le fichier .gitignore en ajoutant cette ligne : ainsi les fichiers html (et autres) ne seront pas mis à jour dans la forge.

docs/build/*

Création d’un fichier requirements.txt

* Si vous n’en avez pas, créer un environnement pour isoler les librairies Python nécessaire au script :

$ python -m venv env_module
$ source env_module/bin/activate
$ pip3 install -r requirements.txt

Dans ce cas, éditez le fichier .gitignore en ajoutant ces 2 lignes :

env_module
env_module/*

* Créer un fichier requirements.txt contenant les modules nécessaire (obtenu avec $ pip freeze), donc avec entre autres ceux nécessaire à la génération de la documentation (d’autres versions peuvent être utilisées) :

sphinx==6.2.1
sphinx-rtd-theme==1.2.1
myst-parser==1.0.0

Création du fichier d’intégration continue

Dans les paramètres, aller dans Settings / pages et créez une page en entrant les informations présentes dans ce fichier :

image: python:latest  # Choisissez l'image Docker appropriee avec Python installe

before_script:  # Creation de l'environnement
  - apt-get update && apt-get install -y make python3
  - pip3 install -r requirements.txt

pages:
  script:
    - make -C docs clean html
    - mv docs/build/html public
  artifacts:
    paths:
      # The folder that contains the files to be exposed at the Page URL
      - public
  rules:
    # This ensures that only pushes to the default branch will trigger
    # a pages deploy
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

* Ce fichier, présent à la racine, se nomme .gitlab-ci.yml
* Ce fichier peut être éditer ensuite soit comme n’importe quel fichier, soit via CI/CD / Editor

Lien

* Pour trouver le lien de la documentation, retourner dans Settings / pages
* L’url devrait ressembler à https://group_name.frama.io/project_name (pour la forge de Framasoft)

Bonus

Fichier gitignore

*~
.#*
#*
#*#
*__pycache__*
*.pyc
docs/build/*
env_module
env_module/*

Fichier conf.py

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


os.environ["PYTHONPATH"] = ".."


# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'ParserHTML'
copyright = '2023, Pierre'
author = 'Pierre'
release = '1.1'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'sphinx_rtd_theme',
    'sphinx.ext.autodoc',  # Autodoc
    'sphinx.ext.autosummary',  # Ne pas ecrire les autoX
    'sphinx.ext.viewcode', # Arborescence
    'myst_parser',    # Add the README
]


templates_path = ['_templates']
exclude_patterns = []

language = 'fr'

os.environ['SPHINX_BUILD'] = '1'

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

autodoc_default_options = {
    'members': True,
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

Inclure le README

* Installer en plus myst-parser si vous ne l’avez pas encore (présent dans le requirements.txt).
* Ajouter au toctree readme.
* Créer le fichier docs/source/readme.rst

README
======

.. include:: ../../README.md
	     :parser: myst_parser.sphinx_