Erste Schritte

Einrichtung Ihres Projekts und Ihrer Entwicklungsumgebung

Erstellen Sie in einem neuen Verzeichnis eine Datei namens README.rst mit dem folgenden Inhalt.

README.rst
Lumache
=======

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.

Es ist ein guter Zeitpunkt, eine virtuelle Python-Umgebung zu erstellen und die erforderlichen Werkzeuge zu installieren. Öffnen Sie dazu ein Kommandozeilenterminal, wechseln Sie mit cd in das gerade erstellte Verzeichnis und führen Sie die folgenden Befehle aus

$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install sphinx

Hinweis

Die oben verwendete Installationsmethode wird detaillierter in PyPI-Paket beschrieben. Für den Rest dieses Tutorials gehen die Anweisungen von einer virtuellen Python-Umgebung aus.

Wenn Sie diese Anweisungen korrekt ausgeführt haben, sollten die Sphinx-Kommandozeilentools verfügbar sein. Sie können eine grundlegende Überprüfung durchführen, indem Sie diesen Befehl ausführen

(.venv) $ sphinx-build --version
sphinx-build 4.0.2

Wenn Sie eine ähnliche Ausgabe sehen, sind Sie auf dem richtigen Weg!

Erstellen des Dokumentationslayouts

Führen Sie dann von der Kommandozeile aus den folgenden Befehl aus

(.venv) $ sphinx-quickstart docs

Dies wird Ihnen eine Reihe von Fragen stellen, die erforderlich sind, um das grundlegende Verzeichnis- und Konfigurationslayout für Ihr Projekt innerhalb des docs-Ordners zu erstellen. Um fortzufahren, beantworten Sie jede Frage wie folgt

  • > Separate source and build directories (y/n) [n]: Geben Sie „y“ (ohne Anführungszeichen) ein und drücken Sie Enter.

  • > Project name: Geben Sie „Lumache“ (ohne Anführungszeichen) ein und drücken Sie Enter.

  • > Author name(s): Geben Sie „Graziella“ (ohne Anführungszeichen) ein und drücken Sie Enter.

  • > Project release []: Geben Sie „0.1“ (ohne Anführungszeichen) ein und drücken Sie Enter.

  • > Project language [en]: Lassen Sie es leer (der Standardwert ist Englisch) und drücken Sie Enter.

Nach der letzten Frage sehen Sie das neue Verzeichnis docs mit folgendem Inhalt.

docs
├── build
├── make.bat
├── Makefile
└── source
   ├── conf.py
   ├── index.rst
   ├── _static
   └── _templates

Der Zweck jeder dieser Dateien ist

build/

Ein leeres Verzeichnis (vorerst), das die gerenderte Dokumentation enthalten wird.

make.bat und Makefile

Praktische Skripte zur Vereinfachung einiger gängiger Sphinx-Operationen, wie z. B. das Rendern des Inhalts.

source/conf.py

Ein Python-Skript, das die Konfiguration des Sphinx-Projekts enthält. Es enthält den Projektnamen und die Freigabe, die Sie sphinx-quickstart angegeben haben, sowie einige zusätzliche Konfigurationsschlüssel.

source/index.rst

Das Stammdokument des Projekts, das als Willkommensseite dient und die Wurzel des „Inhaltsverzeichnisses“ (oder toctree) enthält.

Dank dieses Bootstrap-Schritts haben Sie bereits alles, was Sie brauchen, um die Dokumentation zum ersten Mal als HTML zu rendern. Führen Sie dazu diesen Befehl aus

(.venv) $ sphinx-build -M html docs/source/ docs/build/

Öffnen Sie schließlich docs/build/html/index.html in Ihrem Browser. Sie sollten etwas Ähnliches sehen

Freshly created documentation of Lumache

Frisch erstellte Dokumentation von Lumache

Da haben wir es! Sie haben Ihre erste HTML-Dokumentation mit Sphinx erstellt. Jetzt können Sie damit beginnen, sie anzupassen.