Résumé de la configuration du Sphinx

Aperçu

Sphinx est pratique pour créer de la documentation pour les packages Python. Si vous utilisez sphinx-apidoc et autodoc, les références API seront créées automatiquement à partir de docstrings. Lorsque vous les utilisez, la même configuration est toujours requise, je vais donc les résumer sous forme de mémorandum.

Préparation

Installez sphinx et créez un répertoire pour les documents.

$ pip install sphinx
$ mkdir docs
$ cd docs

Par conséquent, supposons que la structure des répertoires est la suivante.

.
├── README.md
├── docs
├── <your package>
└── tests
 └── Tests

sphinx-quickstart Fondamentalement, par défaut, seuls les éléments suivants sont définis.

• source et build séparés --autodoc: insérer automatiquement des docstrings à partir des modules est oui --mathjax oui si nécessaire --viewcode est également oui si nécessaire

paramètres sphinx-apidoc

Modifiez Makefile pour appeler sphinx-apidoc lors de la compilation du document.

Tout d'abord, créez une cible pour sphinx-apidoc. Le fichier généré automatiquement par sphinx-apidoc est enregistré dans source / modules pour être importé avec des jokers.

Makefile

.PHONY: sphinx-apidoc
sphinx-apidoc:
    sphinx-apidoc -f -o source/modules -M "../<module_path>/"
    #Supprimé car c'est un obstacle lors de l'importation avec glob
    rm source/modules/modules.rst

Ajoutez ensuite la cible sphinx-apidoc aux dépendances de toutes les cibles. Par exemple, pour une cible html

Makefile

.PHONY: html
# html:
html: sphinx-apidoc #Ajoute ça
    $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
    @echo
    @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

Modifier le fichier source

Ajoutez ce qui suit à source / conf.py pour que le package cible soit inclus dans le chemin sphinx.

conf.py

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

Ensuite, pour lire le fichier généré par sphinx-apidoc, ajoutez ce qui suit à source / index.rst.

index.rst

.. toctree::
   :glob:
   :maxdepth: 2

   modules/*

Enfin, modifiez le design à votre guise. J'aime personnellement le Lire le thème de la documentation, alors ajoutez ce qui suit à source / conf.py.

conf.py

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

compiler

Compilez dans le répertoire docs

$ make html