Anhang: Ein Sphinx-Projekt online bereitstellen¶

Wenn Sie bereit sind, Ihr Dokumentationsprojekt der Welt zu zeigen, gibt es viele Möglichkeiten dazu. Da das von Sphinx generierte HTML statisch ist, können Sie den Prozess des Erstellens Ihrer HTML-Dokumentation von der Bereitstellung solcher Dateien auf der Plattform Ihrer Wahl entkoppeln. Sie benötigen keinen ausgeklügelten Server, der Python ausführt: Praktisch jeder Webhosting-Service reicht aus.

Die Herausforderung besteht daher weniger darin, wie oder wo das statische HTML bereitgestellt werden soll, sondern vielmehr darin, einen Workflow zu wählen, der die bereitgestellte Dokumentation automatisch aktualisiert, sobald sich die Quelldateien ändern.

Die folgenden Abschnitte beschreiben einige der verfügbaren Optionen zur Bereitstellung Ihrer Online-Dokumentation und geben einige Hintergrundinformationen. Wenn Sie direkt zum praktischen Teil gelangen möchten, können Sie zu Veröffentlichung Ihrer Dokumentationsquellen springen.

Sphinx-freundliche Bereitstellungsoptionen¶

Es gibt verschiedene Möglichkeiten, Ihre Sphinx-Dokumentation zu hosten. Einige davon sind

Read the Docs: Read the Docs ist ein Online-Dienst, der sich auf das Hosten von technischen Dokumentationen in Sphinx, aber auch in MkDocs spezialisiert hat. Sie bieten eine Reihe von Zusatzfunktionen wie versionierte Dokumentation, Traffic- und Suchanalysen, benutzerdefinierte Domains, benutzerdefinierte Weiterleitungen und mehr.
GitHub Pages: GitHub Pages ist ein einfaches statisches Webhosting, das eng in GitHub integriert ist: Statisches HTML wird von einem der Branches eines Projekts bereitgestellt, und normalerweise werden die Quellen in einem anderen Branch gespeichert, sodass die Ausgabe jedes Mal aktualisiert werden kann, wenn sich die Quellen ändern (z. B. mit GitHub Actions). Die Nutzung ist kostenlos und unterstützt benutzerdefinierte Domains.
GitLab Pages: GitLab Pages ist ein ähnliches Konzept wie GitHub Pages, integriert in GitLab und wird normalerweise mit GitLab CI automatisiert.
Netlify: Netlify ist ein ausgeklügeltes Hosting für statische Websites, das durch clientseitige Webtechnologien wie JavaScript (sogenannte „Jamstack“) erweitert wird. Sie bieten Unterstützung für Headless Content-Management-Systeme und serverloses Computing.
Ihr eigener Server: Sie können Ihren eigenen Webserver jederzeit zur Bereitstellung von Sphinx-HTML-Dokumentationen verwenden. Dies ist die Option, die mehr Flexibilität, aber auch mehr Komplexität bietet.

Alle diese Optionen sind kostenlos, mit der Option, für Zusatzfunktionen zu bezahlen.

Die „Docs as Code“-Philosophie annehmen¶

Die kostenlosen Angebote der meisten der oben genannten Optionen erfordern, dass Ihre Dokumentationsquellen öffentlich zugänglich sind. Darüber hinaus erwarten diese Dienste, dass Sie ein Versionskontrollsystem verwenden, eine Technologie, die die Entwicklung einer Sammlung von Dateien als Reihe von Schnappschüssen („Commits“) verfolgt. Die Praxis, Dokumentationen in Klartextdateien mit denselben Werkzeugen wie für die Softwareentwicklung zu schreiben, ist allgemein als „Docs as Code“ bekannt.

Das derzeit beliebteste Versionskontrollsystem ist Git, ein kostenloses Open-Source-Tool, das das Rückgrat von Diensten wie GitHub und GitLab bildet. Da sowohl Read the Docs als auch Netlify Integrationen mit GitHub und GitLab haben und sowohl GitHub als auch GitLab ein integriertes Pages-Produkt haben, ist der effektivste Weg, Ihre Dokumentation automatisch online zu erstellen, das Hochladen Ihrer Quellen auf einen dieser Git-Hosting-Dienste.

Veröffentlichung Ihrer Dokumentationsquellen¶

GitHub¶

Der schnellste Weg, ein bestehendes Projekt auf GitHub hochzuladen, ist:

Registrieren Sie sich für ein GitHub-Konto.
Erstellen Sie ein neues Repository.
Öffnen Sie die Seite „Dateien hochladen“ Ihres neuen Repositorys.
Wählen Sie die Dateien in Ihrem Dateimanager auf dem Betriebssystem aus (in Ihrem Fall README.rst, lumache.py, die Makefiles im Verzeichnis docs und alles unter docs/source) und ziehen Sie sie per Drag & Drop in die GitHub-Oberfläche, um sie alle hochzuladen.
Klicken Sie auf die Schaltfläche Änderungen committen.

Hinweis

Stellen Sie sicher, dass Sie das Verzeichnis docs/build nicht hochladen, da es die von Sphinx generierte Ausgabe enthält und sich jedes Mal ändert, wenn Sie die Quellen ändern, was Ihren Workflow erschwert.

Diese Schritte erfordern keinen Zugriff auf die Befehlszeile oder die Installation zusätzlicher Software. Um mehr zu erfahren, lesen Sie diese Schnellstart-Anleitung oder konsultieren Sie die offizielle GitHub-Dokumentation

GitLab¶

Ähnlich wie bei GitHub ist der schnellste Weg, Ihr Projekt auf GitLab hochzuladen, die Verwendung der Weboberfläche

Registrieren Sie sich für ein GitLab-Konto.
Erstellen Sie ein neues leeres Projekt.
Laden Sie die Projektdateien (in Ihrem Fall README.rst, lumache.py, die Makefiles im Verzeichnis docs und alles unter docs/source) einzeln über die Schaltfläche Datei hochladen hoch [1].

Auch hier sind keine zusätzlichen Softwareinstallationen auf Ihrem Computer erforderlich. Um mehr zu erfahren, können Sie

Folgen Sie dieser Anleitung, um Git auf Ihrem Rechner zu installieren.
Durchsuchen Sie die GitLab Benutzerdokumentation, um die Möglichkeiten der Plattform zu verstehen.

Hinweis

Stellen Sie sicher, dass Sie das Verzeichnis docs/build nicht hochladen, da es die von Sphinx generierte Ausgabe enthält und sich jedes Mal ändert, wenn Sie die Quellen ändern, was Ihren Workflow erschwert.

Veröffentlichung Ihrer HTML-Dokumentation¶

Read the Docs¶

Read the Docs bietet Integration mit GitHub und GitLab. Der schnellste Weg, um loszulegen, ist, der RTD-Anleitung zu folgen, die lose auf dieser hier basiert. Sie können Ihre Quellen auf GitHub veröffentlichen, wie im vorherigen Abschnitt beschrieben, und dann direkt zu Erstellen eines Read the Docs-Kontos springen. Wenn Sie stattdessen GitLab wählen, ist der Prozess ähnlich.

GitHub Pages¶

GitHub Pages erfordert, dass Sie Ihre Quellen auf GitHub veröffentlichen. Danach benötigen Sie einen automatisierten Prozess, der den Schritt make html jedes Mal ausführt, wenn sich die Quellen ändern. Dies kann mit GitHub Actions erreicht werden.

Nachdem Sie Ihre Quellen auf GitHub veröffentlicht haben, erstellen Sie eine Datei namens .github/workflows/sphinx.yml in Ihrem Repository mit folgendem Inhalt:

.github/workflows/sphinx.yml¶

name: "Sphinx: Render docs"

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
    - uses: actions/checkout@v4
      with:
        persist-credentials: false
    - name: Build HTML
      uses: ammaraskar/sphinx-action@master
    - name: Upload artifacts
      uses: actions/upload-artifact@v4
      with:
        name: html-docs
        path: docs/build/html/
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/build/html

Dies enthält einen GitHub Actions-Workflow mit einem einzigen Job aus vier Schritten:

Die Code-Dateien auschecken.
Die HTML-Dokumentation mit Sphinx erstellen.
Die HTML-Ausgabe an den GitHub Actions-Job anhängen, um sie leichter überprüfen zu können.
Wenn die Änderung im Standard-Branch erfolgt, die Inhalte von docs/build/html nehmen und sie in den gh-pages-Branch pushen.

Als Nächstes müssen Sie die Abhängigkeiten für den Schritt make html angeben. Erstellen Sie dafür eine Datei docs/requirements.txt und fügen Sie folgenden Inhalt hinzu:

docs/requirements.txt¶

furo==2021.11.16

Und schließlich sind Sie bereit, GitHub Pages von einem Branch aus zu veröffentlichen. Gehen Sie dazu zu Einstellungen, dann Seiten in der linken Seitenleiste, wählen Sie den Eintrag Von einem Branch veröffentlichen im Dropdown-Menü „Quelle“ aus, wählen Sie den Branch gh-page im Dropdown-Menü „Branch“ aus und klicken Sie auf Speichern. Nach einigen Minuten sollten Sie Ihre HTML-Ausgabe unter der angegebenen URL sehen können.

GitLab Pages¶

GitLab Pages erfordert andererseits, dass Sie Ihre Quellen auf GitLab veröffentlichen. Wenn Sie soweit sind, können Sie den Prozess des Ausführens von make html mit GitLab CI automatisieren.

Nachdem Sie Ihre Quellen auf GitLab veröffentlicht haben, erstellen Sie eine Datei namens .gitlab-ci.yml in Ihrem Repository mit folgendem Inhalt:

.gitlab-ci.yml¶

stages:
  - deploy

pages:
  stage: deploy
  image: python:3.12-slim
  before_script:
    - apt-get update && apt-get install make --no-install-recommends -y
    - python -m pip install sphinx furo
  script:
    - cd docs && make html
  after_script:
    - mv docs/build/html/ ./public/
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

Dies enthält einen GitLab CI-Workflow mit einem Job aus mehreren Schritten:

Die notwendigen Abhängigkeiten installieren.
Die HTML-Dokumentation mit Sphinx erstellen.
Die Ausgabe an einen bekannten Artefaktort-Speicherort verschieben.

Hinweis

Sie müssen Ihr Konto validieren, indem Sie eine Zahlungsmethode angeben (es wird Ihnen ein kleiner Betrag berechnet, der Ihnen später erstattet wird).

Danach, wenn die Pipeline erfolgreich ist, sollten Sie Ihre HTML-Ausgabe unter der angegebenen URL sehen können.