Installer Sphinx¶
Sphinx is a Python application. It can be installed in one of the ways described below.
After installation, you can check that Sphinx is available by running
$ sphinx-build --version
This should print out the Sphinx version number.
Astuce
For local development, it is generally recommended to install Sphinx into a non-global environment (using for example venv or conda environments). This will allow for the use of separate sphinx versions and third-party extensions for each sphinx project.
PyPI package¶
Sphinx packages are published on the Python Package Index (PyPI). The preferred tool for installing packages from PyPI is pip, which is included in all modern versions of Python.
Run the following command:
$ pip install -U sphinx
Astuce
To avoid issues when rebuilding your environment, it is advisable to pin sphinx and third-party extension versions in a requirements.txt file:
$ pip install -r requirements.txt
Or, if writing documentation for a Python package, place the dependencies in the pyproject.toml file:
$ pip install . --group docs
Conda package¶
To work with conda, you need a conda-based Python distribution such as anaconda, miniconda, miniforge or micromamba.
Sphinx is available both via the anaconda main channel (maintained by Anaconda Inc.)
$ conda install sphinx
as well as via the conda-forge community channel
$ conda install -c conda-forge sphinx
OS-specific package manager¶
You may install a global version of Sphinx into your system using OS-specific package managers. However, be aware that this is less flexible and you may run into compatibility issues if you want to work across different projects.
Linux¶
Debian/Ubuntu¶
Intallez python3-sphinx en utilisant apt-get :
$ apt-get install python3-sphinx
S’il n’est pas déjà présent, ceci installera Python pour vous.
RHEL, CentOS¶
Installez python-sphinx en utilisant yum :
$ yum install python-sphinx
S’il n’est pas déjà présent, ceci installera Python pour vous.
Autres distributions¶
La plupart des distributions Linux ont Sphinx dans leurs dépôts de paquets. En général, le paquet s’appelle python3-sphinx, python-sphinx ou sphinx. Sachez qu’il y a au moins deux autres logiciels avec sphinx dans leur nom : une boîte à outil de reconnaissance vocale (CMU Sphinx) et un moteur de recherche plein texte (Sphinx search).
macOS¶
Sphinx can be installed using Homebrew, MacPorts.
Homebrew¶
$ brew install sphinx-doc
Pour plus d’informations, référez-vous à l”aperçu du paquet.
MacPorts¶
Installez python3x-sphinx en utilisant la commande port :
$ sudo port install py314-sphinx
Pour configurer les chemins des exécutables, utilisez la commande port select :
$ sudo port select --set python python314
$ sudo port select --set sphinx py314-sphinx
Pour plus d’informations, référez-vous à l”aperçu du paquet.
Windows¶
Sphinx can be installed using Chocolatey.
Chocolatey¶
$ choco install sphinx
Il vous faut d’abord installer Chocolatey pour utiliser cette méthode.
Pour plus d’informations, référez-vous à la page Chocolatey.
Docker¶
Des images Docker pour Sphinx sont publiées sur le Docker Hub. Il y a deux types d’images :
La première est destinée à une utilisation standard de Sphinx, et la deuxième principalement à la génération de PDFs en utilisant LaTeX. Veuillez choisir celle correspondant à votre usage.
Note
sphinxdoc/sphinx-latexpdf inclut le paquet TeXLive. De ce fait, l’image est très lourde (plus de 2 Go!).
Indication
Lorsque vous utilisez des images Docker, veuillez utiliser la commande docker run pour invoquer Sphinx. Par exemple, vous pouvez utiliser la commande suivante pour créer un projet Sphinx :
$ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
Et vous pouvez utiliser la commande suivante pour générer des documents HTML :
$ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html
Pour plus de détails, veuillez lire le fichier README des images Docker.
Installation of the latest development release¶
You can install the latest development from PyPI using the --pre flag:
$ pip install -U --pre sphinx
Avertissement
You will not generally need (or want) to do this, but it can be useful if you see a possible bug in the latest stable release.
Installation depuis les sources¶
Vous pouvez installer Sphinx directement depuis un clone du Dépôt Git. Ceci peut être fait soit en clonant le dépôt et en installant depuis le clone local, soit en installant directement avec git.
$ git clone https://github.com/sphinx-doc/sphinx
$ cd sphinx
$ pip install .
$ pip install git+https://github.com/sphinx-doc/sphinx
Vous pouvez aussi télécharger un instantané du dépôt Git aux formats tar.gz ou zip. Une fois téléchargé et extrait, ces sources peuvent être installées avec pip comme ci-dessus.