[PYTHON] Zusammenfassung der Sphinx-Einrichtung

Überblick

Sphinx eignet sich zum Erstellen von Dokumentationen für Python-Pakete. Wenn Sie Sphinx-Apidoc und Autodoc verwenden, werden API-Referenzen automatisch aus Docstrings erstellt. Wenn Sie diese verwenden, ist immer das gleiche Setup erforderlich, daher werde ich sie als Memorandum zusammenfassen.

Vorbereitung

Installieren Sie Sphinx und erstellen Sie ein Verzeichnis für Dokumente.

$ pip install sphinx
$ mkdir docs
$ cd docs

Nehmen Sie daher an, dass die Verzeichnisstruktur wie folgt ist.

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

sphinx-quickstart Grundsätzlich sind standardmäßig nur die folgenden Elemente festgelegt.

• Quelle trennen und bauen --autodoc: Das automatische Einfügen von Dokumentzeichenfolgen aus Modulen ist Ja --mathjax ja wenn nötig --viewcode ist bei Bedarf auch ja

Sphinx-Apidoc-Einstellungen

Bearbeiten Sie Makefile, um beim Kompilieren des Dokuments sphinx-apidoc aufzurufen.

Erstellen Sie zunächst ein Ziel für Sphinx-Apidoc. Die von sphinx-apidoc automatisch generierte Datei wird zum Import mit Platzhaltern in "source / modules" gespeichert.

Makefile

.PHONY: sphinx-apidoc
sphinx-apidoc:
    sphinx-apidoc -f -o source/modules -M "../<module_path>/"
    #Gelöscht, da dies beim Importieren mit glob ein Hindernis darstellt
    rm source/modules/modules.rst

Fügen Sie dann das Sphinx-Apidoc-Ziel zu den Abhängigkeiten aller Ziele hinzu. Zum Beispiel für ein HTML-Ziel

Makefile

.PHONY: html
# html:
html: sphinx-apidoc #Füge das hinzu
    $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
    @echo
    @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

Quelldatei bearbeiten

Fügen Sie Folgendes zu source / conf.py hinzu, damit das Zielpaket im Sphinxpfad enthalten ist.

conf.py

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

Fügen Sie dann zum Lesen der von sphinx-apidoc generierten Datei Folgendes zu "source / index.rst" hinzu.

index.rst

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

   modules/*

Ändern Sie schließlich das Design nach Ihren Wünschen. Ich persönlich mag das Read the docs theme, also füge folgendes zu source / conf.py hinzu.

conf.py

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

kompilieren

Kompilieren Sie im Verzeichnis docs

$ make html