Programmes Python de document HTML avec Sphinx

1.Tout d'abord

Il a été décidé d'étendre la fonctionnalité d'un programme Python développé dans un projet tout en le maintenant dans un autre nouveau projet. En prenant le relais, j'ai décidé de conserver le document HTML généré par Sphinx en tant que document interne. Dans le passé, j'avais de l'expérience dans la conversion en HTML avec Doxygen, et j'intégrais la même quantité d'informations que les commentaires dans le code source, donc je devrais prendre en charge Sphinx. L'arrière-plan.

Le document de conception détaillée est généré automatiquement.

Comme c'est la première fois que vous utilisez Sphinx, enregistrez le contenu du travail. De plus, la règle d'origine est adoptée pour le domaine de docstring.

2. Environnement d'utilisation

Comme suit.

3. Détermination du format docstring

Il existe un format Google et un format numpy, mais reStructureText (communément appelé reST) a été adopté. La raison en est la suivante.

4. Installez Sphinx

C'est une procédure pour l'environnement Windows, mais il semble que macOS et Linux ne soient pas si différents.

pip install Sphinx sphinx-autodoc-typehints
pip install sphinx_rtd_theme

Utilisez sphinx_rtd_theme pour le thème des documents HTML. C'est un peu difficile à voir par défaut.

5. Générer un document HTML

5-1. Exemple de configuration de fichier cible

Supposons la structure de fichiers suivante.

.
├── src/  #Le code source complet est ci-dessous
│   ├── __init__.py
│   ├── Foo.py
│   ├── Bar.py
│   └── Hoge/
│       ├── __init__.py
│       └── Hoge.py
│
└── doc/  #Ceci est le répertoire de travail de Sphinx

5-2. Procédure de génération de documents

Exécutez la commande suivante à partir du terminal.

sphinx-apidoc -F -a -o .\doc .\src
cd doc
make html
.\_build\html\index.html

make htmlGénérez un document html avec. Si vous modifiez la docstring dans le code source, il vous suffit de réexécuter cette commande.

La commande finale index.html lance le navigateur par défaut et ouvre le document HTML.

5-3. À noter

Sphinx semble transmettre le code Python cible au système de traitement, et s'il y a une erreur dans le code cible, une erreur se produira avec `` make html '' et aucun document ne sera généré. Vérifiez le fonctionnement à l'avance.

Par conséquent, par exemple, si le code cible utilise un package qui est unique à Windows, il ne peut pas être documenté dans un environnement macOS ou Linux à moins qu'un package factice ne soit créé par vous-même.

6. Modifiez les paramètres du Sphinx

Si vous conservez la valeur par défaut, ce n'est pas bon, alors ajoutez la ligne suivante au fichier de configuration doc / conf.py```.

doc/conf.py


html_theme = 'sphinx_rtd_theme'    #Spécifier le thème d'affichage
autodoc_typehints = 'description'  #Activer les conseils de type
autoclass_content = 'both'         # __init__()Sortie également
autodoc_default_options = {'private-members': True,   #Méthode privée de sortie
                           'show-inheritance': True}  #Afficher l'héritage

Voici ce que nous faisons ci-dessus.

Après avoir modifié les paramètres, exécutez make html```.

Je me suis référé à cette page pour les paramètres. Importer la documentation de sphinx.ext.autodoc --docstring

Au fait, je l'ai utilisé avec language = en. La mise en page n'était pas correcte avec ja.

7. notation reST

La notation reST de la docstring adoptée est affichée.

7-1. Fichier d'initialisation du package (\ _ \ _ init \ _ \ _. Py)

Une description du package est donnée ici.

__init__.py


"""Titre du package

|Des informations détaillées sont écrites ici.
|Assurez-vous d'ouvrir une ligne à partir du titre du package.
|← Si vous utilisez un bloc de ligne, l'état de saut de ligne est conservé.

:author:Nom de la personne en charge de ce programme
:copyright:Affichage des droits d'auteur
"""

Les chaînes entre deux points, telles que : author: et: copyright: `` ci-dessus, sont appelées des champs et peuvent être définies indépendamment. Lorsque le HTML est sorti, il s'affiche comme suit.

package_header.png

7-2. En-tête de fichier

L'en-tête du fichier est le même que celui du package.

Foo.py


"""Titre du module

|Des informations détaillées sont écrites ici.
|Assurez-vous d'ouvrir une ligne à partir du titre du module.

:note:S'il y a des notes, décrivez-les ici.

:author:Nom de la personne en charge de ce programme
:copyright:Affichage des droits d'auteur
"""

Ce qui précède montre un exemple d'ajout du champ : note:. Utilisez le champ : note: chaque fois que nécessaire comme note dans toutes les docstrings.

7-3. En-tête de classe

La description de l'en-tête de classe s'affiche.

class Foo(object):
    """Résumé de la classe

    |Description détaillée de la classe.
    |Assurez-vous d'ouvrir une ligne du résumé de la classe.
    |← Les blocs de ligne peuvent également être utilisés.
    """

7-4. En-tête de méthode

La description de l'en-tête de la méthode s'affiche.

class Foo(object):

    def method(self, name: str, val: int) -> str:
        '''Résumé de la méthode

        |Description détaillée de la classe.
        |Assurez-vous d'ouvrir une ligne du résumé de la classe.
        |← Les blocs de ligne peuvent également être utilisés.

        :param name:Nom ← Voir l'indice de type si le nom de type est omis
        :param int val:Valeur ← Vous pouvez écrire directement le nom du type
        :returns:(Explication de la valeur de retour)
        :rtype str:← Peut être omis s'il y a un type de retour et un indice de type
        '''
        ...

Pour écrire des indices de type, définissez `` -> None '' pour les méthodes qui n'ont pas de valeur de retour.

2020/8/1: Supplément Quand j'ai regardé le code source de SudachiPy, j'ai trouvé que les indices de type utilisaient uniquement des méthodes publiques. Si la maintenance est difficile, existe-t-il une telle division?

7-5. Membres de la classe d'énumération

La description des membres de la classe d'énumération est décrite comme suit.

class State(enum.Enum):
    """Etat
    """

    UNINIT = enum.auto()  #:Non initialisé
    READY = enum.auto()   #:Attendre
    BUSY = enum.auto()    #:En traitement

7-6. Enroulement de ligne

Si la ligne de description devient longue, vous pouvez continuer avec \ '' ou `` ''.

"""Résumé du module

Description du module. ¥
Cette ligne est affichée à partir de la ligne supérieure sans interruption.
"""

8. Tapez indice

Lorsque j'ai introduit des indices de type à des fins de documentation, je me suis retrouvé coincé avec des indices de type.

8-1. Fait référence à votre classe (renvois)

Si vous utilisez votre classe comme indice de type tel quel, une erreur se produira.

class Foo(object):

    def method(self, obj: Foo) -> None:
        #↑ Foo devient indéfini
        pass

Vous pouvez éviter l'erreur en utilisant une chaîne de caractères comme indiqué ci-dessous.

class Foo(object):

    def method(self, obj: 'Foo') -> None:
        #                  ↑ OK!
        pass

Il a également été écrit correctement sur PEP-484.

PEP-484: Forward references

8-2. List and Dict (Type Aliaces)

Si list ou `` dict est spécifié comme type d'argument ou de valeur de retour, le type de l'élément ne peut pas être décrit. Par conséquent, il est décrit à l'aide de Liste '' et Dict '' du package de saisie.

from typing import List
from typing import Dict
import Bar.Bar

class Foo(object):

    def method(self, bars: List[Bar],
                     map: Dict[str, int]) -> List[str]:
        ...

Les spécifications de Foo.method () sont les suivantes.

Cliquez ici pour plus de détails. PEP-484: Type Aliases

8-3. Éviter et compromettre les importations circulaires (importation circulaire)

Lors de l'importation entre les modules, une erreur se produit lors de l'importation circulaire car elle est dans un état d'importation mutuelle et un message d'erreur tel que ʻImportError: Cannot import name ... `s'affiche. Dans un tel cas, la position est essentiellement «Veuillez changer la structure», mais si la structure ne peut pas être modifiée par tous les moyens, le compromis suivant a été fait.

(1) Abandonnez l'indice de type et écrivez le nom du type dans la docstring (2) Faites du nom du type une chaîne de caractères comme les références directes

Plus tard, dans la correspondance de (2), il a été constaté que la vérification de «F821 nom indéfini» a été interceptée lors du passage à travers flake8, et en fait, toute la correspondance a été effectuée en (1).

Special Thanks

Recommended Posts

Programmes Python de document HTML avec Sphinx
Documenter le code Python avec Doxygen
Déboguer un programme multi-processus python avec VSCode
Créer automatiquement la documentation Python avec Sphinx
Écrire de la documentation dans Sphinx avec Python Livereload
[Python] Un programme qui crée des escaliers avec #
Obtenir le code HTML de l'élément avec du sélénium Python
Créez automatiquement la documentation de l'API Python avec Sphinx
mail html avec image à envoyer avec python
Vie de document confortable avec Sphinx + Drone + S3
Programme d'analyse des contraintes FEM 2D par Python
Génération automatique de documents à partir de docstring avec sphinx
Essayez le scraping HTML avec la bibliothèque Python
Publiez votre propre bibliothèque Python sur Homebrew
[Automation] Lire des documents Word avec Python
FizzBuzz en Python3
Grattage avec Python
Statistiques avec python
Grattage avec Python
Python avec Go
[Note] Exportez le html du site avec python.
Twilio avec Python
Intégrer avec Python
Jouez avec 2016-Python
AES256 avec python
Testé avec Python
Créez rapidement votre propre module avec setuptools (python)
Essayez de générer automatiquement des documents Python avec Sphinx
python commence par ()
avec syntaxe (Python)
Bingo avec python
Zundokokiyoshi avec python
Documentation sur Python
Exemple de programme qui génère un syslog avec la journalisation Python
Excel avec Python
Micro-ordinateur avec Python
Cast avec python
Flux de création de votre propre package avec setup.py avec python
Mémo pour créer votre propre Box avec le Python de Pepper
Pages HTML dynamiques créées avec AWS Lambda et Python
Appelons votre propre bibliothèque C ++ avec Python (Préférences)
De l'achat d'un ordinateur à l'exécution d'un programme sur python
Automatisez Chrome avec Python et Selenium sur votre Chromebook
[Python] Créez un fichier de distribution pour le programme Tkinter avec cx_Freeze
Utilisez des programmes Python avec le plugin de sortie exec_filter de fluentd
Programmez avec votre smartphone n'importe où! (Recommandé pour le langage C / Python)
Utilisez des programmes Python avec le plugin de sortie exec de fluentd
Communication série avec Python
Zip, décompressez avec python
Django 1.11 a démarré avec Python3.6
Jugement des nombres premiers avec Python
Python avec eclipse + PyDev.
Communication de socket avec Python
Analyse de données avec python 2
Grattage en Python (préparation)
Essayez de gratter avec Python.
Apprendre Python avec ChemTHEATER 03
Recherche séquentielle avec Python
"Orienté objet" appris avec python