Python-Dokumentation automatisch erstellen

Dies ist ein Memo über das Verfahren zum automatischen Erstellen eines Python-Dokuments mit Sphinx. Bitte verzeihen Sie mir vorerst, denn es handelt sich um eine Zusammenfassung der Situation des "Umzugs". Sphinx kann automatisch in Python-Code geschriebene Kommentare in HTML konvertieren. Dieses Mal werden wir versuchen, das Dokument mit einer Konfiguration zu automatisieren, in der der Quellcode mehrerer Verzeichnisse, wie unten gezeigt, verknüpft und auf einer gemeinsamen oberen Seite aufgelistet ist.

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

Anfangs ist docs leer, da dies das Verzeichnis ist, in dem die automatisch generierten Dokumente gespeichert werden. Ausführungsumgebung: Ubuntu 18.04 Python：3.6

0. Vorbereitung des Python-Programms

Jeder für das Experiment vorbereitete Python-Code enthält einen Kommentar im Quellcode, wie unten gezeigt. Wenn Sie einen Kommentar in die Dokumentationszeichenfolge schreiben, wird die Beschreibung bei Verwendung von Sphinx automatisch zur HTML-Datei hinzugefügt. Fügen Sie gegebenenfalls eine der Dokumentzeichenfolgen, Google Style usw. hinzu. 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. Installieren Sie die Sphinx

$ sudo apt install python3-sphinx

2. Generieren Sie ein Beispiel-Makefile

2.1 Führen Sie den Sphinx-Schnellstart aus

Der Befehl sphinx-quickstart generiert eine Reihe von Makefiles zum Erstellen von HTML-Dateien im angegebenen Verzeichnis. Wenn Sie den Befehl ausführen, werden Sie aufgefordert, Fragen und Antworten interaktiv einzugeben. Stellen Sie diesmal nur Folgendes ein und führen Sie den Rest standardmäßig aus.

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

Nach dem Ausführen der obigen Schritte werden einige Dateien und Verzeichnisse unter docs erstellt. Bearbeiten Sie dann die generierte Datei für die Umgebung, in der Sie das Dokument generieren möchten.

2.2 Conf.py bearbeiten

In der Nähe der Linie 20 Hier wird die relative Positionsbeziehung zwischen dem Verzeichnis mit dem Beispiel-Makefile und dem Verzeichnis angegeben, in dem die Ziel-Python-Codegruppe bestätigt wurde.

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

In der Nähe der Linie 35 Dies ist eine Option für die automatische Dokumentgenerierung. Weitere Informationen finden Sie unter http://www.sphinx-doc.org/ja/1.2/extensions.html

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

In der Nähe der Linie 98 Ändern Sie das Design der HTML-Seite. (Irgendein)

html_theme = 'default'

3. Generieren Sie automatisch Sphinx-kompatible Dokumente

3.1 Führen Sie sphinx-apidoc aus

Führen Sie den folgenden Befehl aus, um das in den beiden Verzeichnissen vorhandene Codedokument automatisch zu generieren.

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

Nach dem Ausführen des obigen Befehls unter docs dirA / modules.rst, test.rst, test2.srt werden generiert. Jede Datei wird in einem Format namens reStructeredText geschrieben. Siehe unten für Details. https://www.sphinx-doc.org/ja/master/usage/restructuredtext/basics.html modules.rst ist eine Datei, die automatisch generiert wird, wenn shinx-apidoc ausgeführt wird. Eine Liste der im Zielverzeichnis vorhandenen Dateien wird automatisch generiert. Diesmal lautet die Beschreibung beispielsweise wie folgt.

dirA
====

.. toctree::
   :maxdepth: 4

   test
   test2

Dies bedeutet, dass modules.rst eine Baumstruktur hat, die auf test.rst und test2.rst verweist.

3.2 Bearbeiten von index.rst

Beim Ausführen von sphinx-quickstart wurde eine Datei mit dem Namen ./docs/index.rst generiert. Verwenden Sie dies als oberste Seite der HTML-Datei. Wenn Sie aus index.rst auf die Module jedes Verzeichnisses verweisen, werden die Dateien in jedem Verzeichnis automatisch zum HTML-Dokument hinzugefügt. Ändern Sie also ./docs/index.rst.

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

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

   ./dirA/modules
   ./dirB/modules
<Unten weggelassen>

4. Erstellen Sie die HTML-Datei

Erstellen Sie schließlich die HTML-Datei

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

Dadurch wird automatisch eine HTML-Datei unter _build generiert. Doppelklicken Sie auf ./docs/_build/index.html Die diesmal erstellte Datei wird wie folgt angezeigt.

das ist alles. Danke für deine harte Arbeit.

Versuchen Sie, Python-Dokumente automatisch mit Sphinx zu generieren