Sphinx installieren

Sphinx ist eine Python-Anwendung. Es kann auf eine der unten beschriebenen Arten installiert werden.

Nach der Installation können Sie überprüfen, ob Sphinx verfügbar ist, indem Sie Folgendes ausführen:

$ sphinx-build --version

Dadurch sollte die Sphinx-Versionsnummer ausgegeben werden.

Tipp

Für die lokale Entwicklung wird generell empfohlen, Sphinx in eine nicht-globale Umgebung zu installieren (z.B. mit venv oder conda-Umgebungen). Dies ermöglicht die Verwendung separater Sphinx-Versionen und von Drittanbieter-Erweiterungen für jedes Sphinx-Projekt.

PyPI-Paket

Sphinx-Pakete werden im Python Package Index (PyPI) veröffentlicht. Das bevorzugte Werkzeug zur Installation von Paketen aus PyPI ist pip, das in allen modernen Python-Versionen enthalten ist.

Führen Sie den folgenden Befehl aus

$ pip install -U sphinx

Tipp

Um Probleme beim Neuerstellen Ihrer Umgebung zu vermeiden, ist es ratsam, Sphinx und die Versionen von Drittanbieter-Erweiterungen in einer requirements.txt-Datei zu fixieren.

$ pip install -r requirements.txt

Oder, wenn Sie Dokumentation für ein Python-Paket schreiben, legen Sie die Abhängigkeiten in der pyproject.toml-Datei ab.

$ pip install . --group docs

Conda-Paket

Um mit conda zu arbeiten, benötigen Sie eine auf conda basierende Python-Distribution wie anaconda, miniconda, miniforge oder micromamba.

Sphinx ist sowohl über den anaconda main-Kanal (gepflegt von Anaconda Inc.) verfügbar

$ conda install sphinx

als auch über den Community-Kanal conda-forge.

$ conda install -c conda-forge sphinx

Betriebssystemspezifischer Paketmanager

Sie können eine globale Version von Sphinx über betriebssystemspezifische Paketmanager in Ihrem System installieren. Seien Sie sich jedoch bewusst, dass dies weniger flexibel ist und Sie Kompatibilitätsprobleme haben könnten, wenn Sie mit verschiedenen Projekten arbeiten möchten.

Linux

Debian/Ubuntu

Installieren Sie entweder python3-sphinx mit apt-get.

$ apt-get install python3-sphinx

Falls es noch nicht vorhanden ist, wird dies Python für Sie installieren.

RHEL, CentOS

Installieren Sie python-sphinx mit yum.

$ yum install python-sphinx

Falls es noch nicht vorhanden ist, wird dies Python für Sie installieren.

Andere Distributionen

Die meisten Linux-Distributionen haben Sphinx in ihren Paket-Repositories. Normalerweise heißt das Paket python3-sphinx, python-sphinx oder sphinx. Beachten Sie, dass es mindestens zwei andere Pakete mit sphinx im Namen gibt: ein Speech-Recognition-Toolkit (CMU Sphinx) und eine Volltextsuchdatenbank (Sphinx search).

macOS

Sphinx kann mit Homebrew, MacPorts installiert werden.

Homebrew

$ brew install sphinx-doc

Weitere Informationen finden Sie in der Paketübersicht.

MacPorts

Installieren Sie entweder python3x-sphinx mit port.

$ sudo port install py313-sphinx

Verwenden Sie den Befehl port select, um die ausführbaren Pfade einzurichten.

$ sudo port select --set python python313
$ sudo port select --set sphinx py313-sphinx

Weitere Informationen finden Sie in der Paketübersicht.

Windows

Sphinx kann mit Chocolatey installiert werden.

Chocolatey

$ choco install sphinx

Sie müssen Chocolatey installieren, bevor Sie dies ausführen können.

Weitere Informationen finden Sie auf der Chocolatey-Seite.

Docker

Docker-Images für Sphinx werden auf Docker Hub veröffentlicht. Es gibt zwei Arten von Images:

Ersteres wird für den Standardgebrauch von Sphinx verwendet, letzteres hauptsächlich für PDF-Builds mit LaTeX. Wählen Sie eines für Ihren Zweck.

Hinweis

sphinxdoc/sphinx-latexpdf enthält TeXLive-Pakete. Das Image ist daher sehr groß (über 2 GB!).

Hinweis

Wenn Sie Docker-Images verwenden, verwenden Sie bitte den Befehl docker run, um Sphinx-Befehle aufzurufen. Sie können beispielsweise den folgenden Befehl verwenden, um ein Sphinx-Projekt zu erstellen:

$ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart

Und Sie können den folgenden Befehl verwenden, um die HTML-Dokumentation zu erstellen:

$ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html

Weitere Details finden Sie in der README-Datei der Docker-Images.

Installation der neuesten Entwicklungsversion

Sie können die neueste Entwicklungsversion von PyPI mit dem Flag --pre installieren.

$ pip install -U --pre sphinx

Warnung

Dies werden Sie im Allgemeinen nicht benötigen (oder wollen), aber es kann nützlich sein, wenn Sie einen möglichen Fehler in der neuesten stabilen Version feststellen.

Installation aus dem Quellcode

Sie können Sphinx direkt aus einem Klon des Git-Repositorys installieren. Dies kann entweder durch Klonen des Repos und Installation aus dem lokalen Klon erfolgen oder einfach durch direkte Installation über git.

$ git clone https://github.com/sphinx-doc/sphinx
$ cd sphinx
$ pip install .

$ pip install git+https://github.com/sphinx-doc/sphinx

Sie können auch einen Snapshot des Git-Repos im tar.gz- oder zip-Format herunterladen. Nach dem Herunterladen und Entpacken können diese wie oben mit pip installiert werden.