python-sphinx Tutorial
Erste Schritte mit Python-Sphinx
Suche…
Bemerkungen
Dieser Abschnitt bietet einen Überblick über Python-Sphinx und warum ein Entwickler sie verwenden möchte.
Es sollte auch alle großen Themen in Python-Sphinx erwähnen und auf die verwandten Themen verweisen. Da die Dokumentation für Python-Sphinx neu ist, müssen Sie möglicherweise erste Versionen dieser verwandten Themen erstellen.
Installation oder Setup
Da Sphinx im Python Package Index verfügbar ist, kann es mit pip installiert werden:
pip install Sphinx
oder Sie können auch mit easy_install installieren
easy_install -U sphinx
Dann können Sie die korrekte Installation überprüfen, indem Sie den folgenden Befehl ausführen:
> sphinx-quickstart --version
Sphinx v1.4.1
Bevor Sie fortfahren, müssen Sie einen bestimmten Codestil für Python PEP 8 beachten . Wenn Sie die PEP 8- Richtlinie befolgt haben, können Sie die Dokumentstruktur in Sphinx definieren und mit dem Erstellen Ihrer Dokumentation beginnen .
Schnellstart
Um zu beginnen, gehen Sie zum Stammverzeichnis des Projektverzeichnisses und führen Sie Folgendes aus:
$ sphinx-quickstart
Sie erhalten Optionen, um Dokumentation für Ihr Projekt zu erstellen. Für die Standardeinstellung folgen Sie den folgenden Befehlen:
Prompt Choice
> Root path for the documentation [.]: <ENTER>
> Separate source and build directories (y/N) [n]: y
> Name prefix for templates and static dir [_]: <ENTER>
> Project name: an_example_pypi_project
> Author name(s): Andrew Carter
> Project version: 0.0.1
> Project release [0.0.1]: <ENTER>
> Source file suffix [.rst]: <ENTER>
> Name of your master document (without suffix) [index]: <ENTER>
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: n
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
> todo: write “todo” entries that can be shown or hidden on build (y/N) [n]: n
> coverage: checks for documentation coverage (y/N) [n]: n
> pngmath: include math, rendered as PNG images (y/N) [n]: n
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/N) [n]: y
> Create Makefile? (Y/n) [y]: n
> Create Windows command file? (Y/n) [y]: n
Bei erfolgreicher Ausführung können Sie die Datei config.py in Ihrem doc / source-Verzeichnis Ihres Projekts finden. Diese Datei hat Einfluss auf die grundlegende Struktur, wie Ihr Dokument generiert wird, wenn Sie den Build-Befehl wie folgt ausführen
$ sphinx-build -b html sourcedir builddir
Detaillierte Anweisungen finden Sie unter: https://pythonhosted.org/an_example_pypi_project/sphinx.html