Erste Schritte zur Dokumentation Ihres Projekts mit Sphinx

Erstellung Ihrer HTML-Dokumentation

Die Datei index.rst, die sphinx-quickstart erstellt hat, enthält bereits einige Inhalte und wird als Titelseite Ihrer HTML-Dokumentation gerendert. Sie ist in reStructuredText geschrieben, einer leistungsstarken Auszeichnungssprache.

Ändern Sie die Datei wie folgt:

docs/source/index.rst
Welcome to Lumache's documentation!
===================================

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.  It pulls data from the `Open Food
Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
*intuitive* API.

.. note::

   This project is under active development.

Dies zeigt mehrere Funktionen der reStructuredText-Syntax, darunter:

  • eine Abschnittsüberschrift mit === für die Unterstreichung,

  • zwei Beispiele für Inline-Markup: **starke Betonung** (typischerweise fett) und *Betonung* (typischerweise kursiv),

  • ein inline externer Link,

  • und eine note Admonition (eine der verfügbaren Direktiven)

Um sie nun mit dem neuen Inhalt zu rendern, können Sie wie zuvor den Befehl sphinx-build verwenden oder das Komfort-Skript wie folgt nutzen:

(.venv) $ cd docs
(.venv) $ make html

Nach Ausführung dieses Befehls werden Sie sehen, dass index.html die neuen Änderungen widerspiegelt!

Erstellung Ihrer Dokumentation in anderen Formaten

Sphinx unterstützt neben HTML eine Vielzahl von Formaten, darunter PDF, EPUB, und mehr. Um beispielsweise Ihre Dokumentation im EPUB-Format zu erstellen, führen Sie diesen Befehl im Verzeichnis docs aus:

(.venv) $ make epub

Danach sehen Sie die Dateien, die dem E-Book entsprechen, unter docs/build/epub/. Sie können entweder Lumache.epub mit einem EPUB-kompatiblen E-Book-Viewer wie Calibre öffnen oder index.xhtml in einem Webbrowser in der Vorschau anzeigen.

Hinweis

Um eine vollständige Liste der möglichen Ausgabeformate sowie einige nützliche Zusatzbefehle anzuzeigen, können Sie make help ausführen.

Jedes Ausgabeformat hat spezifische Konfigurationsoptionen, die Sie anpassen können, einschließlich EPUB. Zum Beispiel ist der Standardwert von epub_show_urls inline, was bedeutet, dass URLs standardmäßig direkt nach dem entsprechenden Link in Klammern angezeigt werden. Sie können dieses Verhalten ändern, indem Sie den folgenden Code am Ende Ihrer conf.py hinzufügen:

docs/source/conf.py
# EPUB options
epub_show_urls = 'footnote'

Mit diesem Konfigurationswert und nach erneuter Ausführung von make epub werden Sie feststellen, dass URLs nun als Fußnoten erscheinen, was den Text übersichtlicher macht. Super! Lesen Sie weiter, um andere Möglichkeiten zur Anpassung von Sphinx zu entdecken.

Hinweis

Die Erstellung eines PDFs mit Sphinx kann durch Ausführung von make latexpdf erfolgen, vorausgesetzt, das System verfügt über eine funktionierende LaTeX-Installation, wie in der Dokumentation von sphinx.builders.latex.LaTeXBuilder erklärt. Obwohl dies durchaus machbar ist, sind solche Installationen oft groß und im Allgemeinen erfordert LaTeX in einigen Fällen eine sorgfältige Konfiguration, daher ist die PDF-Erstellung für dieses Tutorial nicht relevant.