Essayez de générer automatiquement des documents Python avec Sphinx

Créer automatiquement la documentation Python

Ceci est un mémo sur la procédure de création automatique d'un document python à l'aide de sphinx. Pour le moment, pardonnez-moi car il s'agit d'un résumé de la situation de "déplacement". sphinx peut convertir automatiquement les commentaires écrits en code python en html. Cette fois, nous allons essayer d'automatiser le document avec une configuration dans laquelle le code source de plusieurs répertoires comme indiqué ci-dessous est lié et répertorié sur une page d'accueil commune.

 - dirA
    - test.py
    - test2.py
 - dirB
    - testB.py
 - docs 

Initialement, docs est vide car il s'agit du répertoire dans lequel les documents générés automatiquement seront stockés. Environnement d'exécution: Ubuntu 18.04 Python：3.6

0. Préparation du programme Python

Chaque code python préparé pour l'expérience a un commentaire dans le code source comme indiqué ci-dessous. Si vous écrivez un commentaire dans la notation docstring, la description sera automatiquement ajoutée au fichier HTML lors de l'utilisation de sphinx. Ajoutez l'une des docstrings, Google Style, etc. selon le cas. https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

class test():
    """test Class
    """
    
    def __init__(self):
        self.val = 0
    
    def SetVal(self, val):
       """SetVal function
       """
       self.val=val

    def GetVal(self):
        """GetVal function
        """
        return self.val

1. Installez sphinx

$ sudo apt install python3-sphinx

2. Générez un exemple de Makefile

2.1 Exécuter sphinx-quickstart

La commande sphinx-quickstart générera un ensemble de Makefiles pour créer des fichiers html dans le répertoire spécifié. Lorsque vous exécutez la commande, vous serez invité à saisir des questions et des réponses de manière interactive. Cette fois, définissez uniquement ce qui suit et exécutez le reste par défaut.

$sphinx-quickstart docs
...
ProjectName: sphinxTest
Auther name: hoge
Language: ja

Après avoir exécuté ce qui précède, certains fichiers et répertoires seront créés sous docs. Modifiez ensuite le fichier généré pour l'environnement dans lequel vous générez le document.

2.2 Modification de conf.py

• Près de la ligne 20 La relation de position relative entre le répertoire contenant l'exemple de Makefile et le répertoire dans lequel le groupe de code Python cible a été confirmé est spécifiée ici.

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

• Près de la ligne 35 Il s'agit d'une option pour la génération automatique de documents. Pour plus d'informations http://www.sphinx-doc.org/ja/1.2/extensions.html

extensions = ["sphinx.ext.autodoc","sphinx.ext.autosummary"]

• Près de la ligne 98 Modifiez la conception de la page HTML. (Tout)

html_theme = 'default'

3. Générez automatiquement des documents compatibles Sphinx

3.1 Exécuter sphinx-apidoc

Exécutez la commande suivante pour générer automatiquement le document de code qui existe dans les deux répertoires.

$ sphinx-apidoc -f -o docs/dirA ./dirA
$ sphinx-apidoc -f -o docs/dirB ./dirB

Après avoir exécuté la commande ci-dessus, sous docs dirA / modules.rst, test.rst, test2.srt sont générés. Chaque fichier est écrit dans un format appelé reStructeredText. Voir ci-dessous pour plus de détails. https://www.sphinx-doc.org/ja/master/usage/restructuredtext/basics.html modules.rst est un fichier généré automatiquement lors de l'exécution de shinx-apidoc. Une liste des fichiers existant sous le répertoire cible est automatiquement générée. Par exemple, cette fois, la description est la suivante.

dirA
====

.. toctree::
   :maxdepth: 4

   test
   test2

Cela signifie que modules.rst a une structure arborescente qui fait référence à test.rst et test2.rst.

3.2 Édition de index.rst

Lorsque j'ai exécuté sphinx-quickstart, un fichier appelé ./docs/index.rst a été généré. Utilisez ceci comme première page du fichier html. Si vous vous référez aux modules de chaque répertoire depuis index.rst, les fichiers de chaque répertoire seront automatiquement ajoutés au document html. Alors, modifiez ./docs/index.rst.

Welcome to test's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   ./dirA/modules
   ./dirB/modules
<Omis ci-dessous>

4. Créez le fichier html

Enfin, construisez le fichier html

$ sphinx-build -b html ./docs ./docs/_build/

Cela générera automatiquement un fichier html sous _build. Double-cliquez sur ./docs/_build/index.html Le fichier créé cette fois apparaîtra comme indiqué ci-dessous.

c'est tout. Je vous remercie pour votre travail acharné.