HTML-Dokument Python-Programme mit Sphinx
1. Zuallererst
Es wurde beschlossen, die Funktionalität eines in einem Projekt entwickelten Python-Programms zu erweitern und es in einem anderen neuen Projekt beizubehalten. Durch die Übernahme habe ich beschlossen, das von Sphinx generierte HTML-Dokument als internes Dokument beizubehalten. In der Vergangenheit hatte ich Erfahrung mit der Konvertierung in HTML mit Doxygen und habe die gleiche Menge an Informationen wie Kommentare in den Quellcode eingebettet, sodass ich Sphinx unterstützen sollte. Der Hintergrund.
Das detaillierte Konstruktionsdokument wird automatisch generiert.
Da ich Sphinx zum ersten Mal benutze, werde ich den Arbeitsinhalt aufzeichnen. Darüber hinaus wird die ursprüngliche Regel für den Bereich docstring übernommen.
2. Nutzungsumgebung
Wie folgt.
- Windows 10 Pro
- Python 3.7.4
- Sphinx 3.1.2
Es gibt das Google-Format und das Numpy-Format, aber reStructureText (allgemein als reST bekannt) wurde übernommen. Der Grund ist wie folgt.
- Kurze Notation
- Standard, daher keine zusätzliche Verpackung erforderlich
- Unterstützt Typhinweise
- Wenn Sie einen Typhinweis übernehmen, möchten Sie vermeiden, dass Sie dasselbe mit dem Typhinweis und der Dokumentzeichenfolge schreiben
- Wenn Sie dagegen einen Typhinweis schreiben, müssen Sie die Typinformationen von docstring nicht schreiben.
4. Installieren Sie Sphinx
Es ist ein Verfahren für die Windows-Umgebung, aber es scheint, dass MacOS und Linux nicht so unterschiedlich sind.
pip install Sphinx sphinx-autodoc-typehints
pip install sphinx_rtd_theme
sphinx_rtd_theme wird für das Thema von HTML-Dokumenten verwendet.
Es ist standardmäßig etwas schwer zu erkennen.
5. Generieren Sie ein HTML-Dokument
5-1. Beispiel für die Konfiguration der Zieldatei
Nehmen Sie die folgende Dateistruktur an.
.
├── src/ #
│ ├── __init__.py
│ ├── Foo.py
│ ├── Bar.py
│ └── Hoge/
│ ├── __init__.py
│ └── Hoge.py
│
└── doc/ #Dies ist das Arbeitsverzeichnis von Sphinx
- Speichern Sie den gesamten Quellcode in
`src /` - Quellcode hat Unterverzeichnisse (Unterpakete)
- Die von Sphinx generierte Datei wird in
`doc /`ausgegeben
5-2. Verfahren zur Dokumentenerstellung
Führen Sie den folgenden Befehl vom Terminal aus.
sphinx-apidoc -F -a -o .\doc .\src
cd doc
make html
.\_build\html\index.html
make htmlGenerieren Sie ein HTML-Dokument mit. Wenn Sie die Dokumentzeichenfolge im Quellcode ändern, müssen Sie diesen Befehl nur erneut ausführen.
Der letzte Befehl index.html startet den Standardbrowser und öffnet das HTML-Dokument.
5-3. Dinge zu beachten
Sphinx scheint den Python-Zielcode an das Verarbeitungssystem zu übergeben, und wenn der Zielcode einen Fehler enthält, tritt ein Fehler mit `` `make html``` auf und es wird kein Dokument generiert. Überprüfen Sie den Betrieb im Voraus.
Wenn der Zielcode beispielsweise ein für Windows eindeutiges Paket verwendet, kann es in einer MacOS- oder Linux-Umgebung nur dokumentiert werden, wenn Sie selbst ein Dummy-Paket erstellt haben.
6. Ändern Sie die Sphinx-Einstellungen
Wenn Sie die Standardeinstellung beibehalten, ist dies nicht gut. Fügen Sie daher die folgende Zeile zur Einstellungsdatei `` `doc / conf.py``` hinzu.
doc/conf.py
html_theme = 'sphinx_rtd_theme' #Geben Sie das Anzeigethema an
autodoc_typehints = 'description' #Typhinweise aktivieren
autoclass_content = 'both' # __init__()Auch ausgeben
autodoc_default_options = {'private-members': True, #Private Methode ausgeben
'show-inheritance': True} #Vererbung anzeigen
Was wir oben tun, ist wie folgt.
- Ändern Sie das Anzeigethema vom Standard zum angegebenen Thema
- Stellen Sie die Verwendung von Typhinweisen ein
- Standardmäßig ist \ _ \ _ init \ _ \ _ () ausgeblendet. Stellen Sie daher die Anzeige ein.
- Private Methoden sind standardmäßig ausgeblendet. Stellen Sie sie daher so ein, dass sie angezeigt werden
- Für Methoden, die mit "_" beginnen, z. B. "_method1 ()" oder "__method2 ()"
- Standardmäßig sind Vererbungsinformationen ausgeblendet. Stellen Sie sie daher so ein, dass sie angezeigt werden.
Führen Sie nach dem Ändern der Einstellungen `` `make html``` aus.
Ich habe auf diese Seite für die Einstellungen verwiesen. Dokumentation aus sphinx.ext.autodoc --docstring importieren
Übrigens habe ich es mit language = en benutzt. Das Layout sah mit "ja" nicht richtig aus.
7. reST-Notation
Die reST-Notation der übernommenen Dokumentzeichenfolge wird angezeigt.
7-1. Paketinitialisierungsdatei (\ _ \ _ init \ _ \ _. Py)
Eine Beschreibung des Pakets finden Sie hier.
__init__.py
"""Pakettitel
|Detaillierte Informationen finden Sie hier.
|Stellen Sie sicher, dass Sie eine Zeile aus dem Pakettitel öffnen.
|← Wenn Sie einen Zeilenblock verwenden, bleibt der Zeilenumbruchstatus erhalten.
:author:Name der Person, die für dieses Programm verantwortlich ist
:copyright:Copyright-Anzeige
"""
Zeichenfolgen zwischen Doppelpunkten, z. B. `: author:` und `: copyright:` oben, werden als Felder bezeichnet und können unabhängig definiert werden. Wenn HTML ausgegeben wird, wird es wie folgt angezeigt.
7-2. Dateikopf
Der Dateikopf ist der gleiche wie das Paket.
Foo.py
"""Modultitel
|Detaillierte Informationen finden Sie hier.
|Stellen Sie sicher, dass Sie eine Zeile des Modultitels öffnen.
:note:Wenn es Notizen gibt, beschreiben Sie diese hier.
:author:Name der Person, die für dieses Programm verantwortlich ist
:copyright:Copyright-Anzeige
"""
Das Obige zeigt ein Beispiel für das Hinzufügen des Felds : note:.
Verwenden Sie das Feld : note:, wo immer dies erforderlich ist, als Notiz in allen Dokumentzeichenfolgen.
7-3. Klassenkopf
Die Beschreibung des Klassenkopfes wird angezeigt.
class Foo(object):
"""Klassenübersicht
|Detaillierte Beschreibung der Klasse.
|Stellen Sie sicher, dass Sie eine Zeile aus der Klassenübersicht öffnen.
|← Linienblöcke können ebenfalls verwendet werden.
"""
7-4. Methodenkopf
Die Beschreibung des Methodenheaders wird angezeigt.
class Foo(object):
def method(self, name: str, val: int) -> str:
'''Methodenübersicht
|Detaillierte Beschreibung der Klasse.
|Stellen Sie sicher, dass Sie eine Zeile aus der Klassenübersicht öffnen.
|← Linienblöcke können ebenfalls verwendet werden.
:param name:Name ← Siehe Typhinweis, wenn der Typname weggelassen wird
:param int val:Wert ← Sie können den Typnamen direkt schreiben
:returns:(Erklärung des Rückgabewerts)
:rtype str:← Kann weggelassen werden, wenn ein Rückgabetyp und ein Typhinweis vorhanden sind
'''
...
Um Typhinweise zu schreiben, setzen Sie `` `-> None``` für Methoden, die keinen Rückgabewert haben.
2020/8/1: Ergänzung Als ich mir den SudachiPy-Quellcode ansah, stellte ich fest, dass Typhinweise nur öffentliche Methoden verwendeten. Wenn die Wartung schwierig ist, gibt es eine solche Aufteilung?
7-5. Mitglieder der Aufzählungsklasse
Die Beschreibung der Mitglieder der Aufzählungsklasse wird wie folgt beschrieben.
class State(enum.Enum):
"""Zustand
"""
UNINIT = enum.auto() #:Nicht initialisiert
READY = enum.auto() #:Warten
BUSY = enum.auto() #:wird bearbeitet
7-6. Zeilenumbruch
Wenn die Beschreibungszeile lang wird, können Sie mit `\` oder `\` fortfahren.
"""Modulübersicht
Modulbeschreibung. ¥
Diese Zeile wird von der obersten Zeile ohne Unterbrechungen angezeigt.
"""
8. Geben Sie einen Hinweis ein
Als ich Typhinweise zum Zwecke der Dokumentation einführte, blieb ich bei Typhinweisen hängen.
8-1. Bezieht sich auf Ihre Klasse (Weiterleitungsreferenzen)
Wenn Sie Ihre Klasse so wie sie ist als Typhinweis verwenden, tritt ein Fehler auf.
class Foo(object):
def method(self, obj: Foo) -> None:
#↑ Foo wird undefiniert
pass
Sie können den Fehler vermeiden, indem Sie eine Zeichenfolge wie unten gezeigt verwenden.
class Foo(object):
def method(self, obj: 'Foo') -> None:
# ↑ OK!
pass
Es wurde auch richtig auf PEP-484 geschrieben.
8-2. Liste und Diktat (Typ Aliaces)
Wenn als Argumenttyp oder Rückgabewert `list``` oder` dict angegeben ist, kann der Typ des Elements nicht beschrieben werden. Daher wird es mit `` `List und` `` Dict``` des Tipppakets beschrieben.
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]:
...
Die Spezifikationen von Foo.method () lauten wie folgt.
- Das Argument `` `Bars``` ist eine Liste von Objekten der Klasse Bar
- Das Argument `` `map``` ist ein Wörterbuch, dessen Schlüssel eine Zeichenfolge und dessen Wert eine Ganzzahl ist.
- Der Rückgabewert ist eine Liste von Zeichenfolgen
Hier klicken für Details. PEP-484: Type Aliases
8-3 Vermeiden und Kompromittieren von Zirkularimporten (Zirkularimport)
Beim Importieren zwischen Modulen tritt beim zirkulären Import ein Fehler auf, da er sich in einem gegenseitigen Importstatus befindet, und die Fehlermeldung "ImportError: Name kann nicht importiert werden ..." wird angezeigt. In einem solchen Fall lautet die Haltung im Grunde "Bitte ändern Sie die Struktur". Wenn die Struktur jedoch nicht mit allen Mitteln geändert werden kann, wurde der folgende Kompromiss eingegangen.
(1) Geben Sie den Typhinweis auf und schreiben Sie den Typnamen in die Dokumentzeichenfolge (2) Machen Sie den Typnamen zu einer Zeichenfolge wie Forward Refences
Später wurde in der Korrespondenz von (2) festgestellt, dass die Prüfung des "undefinierten Namens F821" beim Durchlaufen von flake8 abgefangen wurde, und tatsächlich wurde die gesamte Korrespondenz in (1) durchgeführt.
Special Thanks
Recommended Posts