Installer Sphinx

Résumé

Sphinx is written in Python and supports Python 3.9+. It builds upon the shoulders of many third-party libraries such as Docutils and Jinja, which are installed when Sphinx is installed.

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 peut être installé avec Homebrew, MacPorts, ou comme élément d’une distribution Python telle qu”Anaconda.

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 py39-sphinx

Pour configurer les chemins des exécutables, utilisez la commande port select :

$ sudo port select --set python python39
$ sudo port select --set sphinx py39-sphinx

Pour plus d’informations, référez-vous à l”aperçu du paquet.

Anaconda

$ conda install sphinx

Windows

Sphinx peut être installé en utilisant Chocolatey ou manuellement.

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.

Autres méthodes

La plupart des utilisateurs de Windows n’ont pas Python installé par défaut, il faut donc commencer par l’installation de Python lui-même. Pour vérifier si vous disposez déjà de Python installé, ouvrez l”Invite de commande (⊞Win-r et tapez cmd). Une fois l’invite ouverte, tapez python --version puis Entrée. Si Python est installé, vous verrez la version installée de Python s’afficher à l’écran. Si Python n’est pas installé, référez-vous aux guides d’installation sous Windows du Guide de l’auto-stoppeur Python. Vous devez installer Python 3.

Une fois Python installé, vous pouvez installer Sphinx en utilisant pip. Référez-vous aux instructions d’installation de pip ci-dessous pour plus d’informations.

Installation depuis PyPI

Les paquets Sphinx sont publiés dans l”Index des Paquets Python (PyPI). L’outil préféré pour l’installation de paquets depuis PyPI est pip. Cet outil est fournit avec toutes les versions modernes de Python.

Sous Linux et macOS, vous devriez ouvrir un terminal et exécuter la commande suivante :

$ pip install -U sphinx

Sous Windows, vous devriez ouvrir une Invite de commande (⊞Win-r et tapez cmd) et exécuter la commande :

C:\> pip install -U sphinx

Après installation, exécutez la commande sphinx-build --version à l’invite de commande. Si tout a bien fonctionné, vous verrez le numéro de version du paquet Sphinx que vous venez d’installer.

L’installation depuis PyPI vous permet aussi d’installer la dernière version de développement. Vous n’aurez généralement pas besoin de (ni ne voudrez) le faire, mais cela peut s’avérer utile si vous rencontrez un possible bogue dans la dernière version stable. Pour ce faire, utilisez l’option --pre :

$ pip install -U --pre sphinx

Environnements virtuels

Lorsque vous installez Sphinx avec pip, il est fortement recommandé d’utiliser les environnements virtuels qui isolent les paquets installés des paquets système, supprimant ainsi le besoin d’utiliser des privilèges administrateur. Pour créer un environnement virtuel dans le répertoire .venv, utilisez la commande suivante :

$ python -m venv .venv

Voir aussi

venv – creating virtual environments

Avertissement

Notez que sous certaines distributions Linux, telles que Debian et Ubuntu, ceci peut nécessiter une étape d’installation supplémentaire comme la suivante :

$ apt-get install python3-venv

Docker

Des images Docker pour Sphinx sont publiées sur le Hub Docker. 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 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.