Instalando Sphinx

Visão geral

Sphinx é escrito em Python e suporta Python 3.9+. Ele se baseia em muitas bibliotecas de terceiros, como Docutils e Jinja, que são instaladas quando o Sphinx é instalado.

Linux

Debian/Ubuntu

Instale python3-sphinx usando apt-get:

$ apt-get install python3-sphinx

Se Python não estiver presente, este também será automaticamente instalado.

RHEL, CentOS

Instale python-sphinx usando yum:

$ yum install python-sphinx

Se Python não estiver presente, este também será automaticamente instalado.

Outras distribuições

Muitas distribuições Linux possuem Sphinx em seus repositórios. Normalmente o pacote tem o nome python3-sphinx, python-sphinx ou sphinx. Preste atenção pois existem ao menos dois outros pacotes com sphinx em seus nomes: uma ferramenta de reconhecimento voz (CMU Sphinx) e outra mecanismo banco de dados texto completo (Sphinx search).

macOS

O Sphinx pode ser instalado usando Homebrew, MacPorts ou como parte de uma distribuição do Python, como Anaconda.

Homebrew

$ brew install sphinx-doc

Para mais informações, consulte a visão geral do pacote.

MacPorts

Instale python3x-sphinx usando port:

$ sudo port install py39-sphinx

Para configurar os caminhos dos executáveis, use o comando port select:

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

Para mais informações, consulte a visão geral do pacote.

Anaconda

$ conda install sphinx

Windows

Sphinx pode ser instalado usando Chocolatey ou instalado manualmente.

Chocolatey

$ choco install sphinx

Você precisaria instalar Chocolatey antes de executar isso.

Para mais informações, consulte a página do chocolatey.

Outros Métodos

A maioria dos usuários do Windows não tem o Python instalado por padrão, então começamos com a instalação do próprio Python. Para verificar se você já tem o Python instalado, abra o Prompt de Comando (⊞Win-r e digite cmd). Quando o prompt de comando estiver aberto, digite python --version e pressione Enter. Se o Python estiver instalado, você verá a versão do Python impressa na tela. Se você não tem o Python instalado, consulte o guia de instalação do Python no Hitchhikers Guide to Python’s para o Python. Você deve instalar o Python 3.

Quando Python estiver instalado, poderá instalar Sphinx usando pip. Consulte as instruções de instalação do pip abaixo para mais informação.

Instalar a partir do PyPI

Os pacotes do Sphinx são publicados no Python Package Index. A ferramenta preferida para instalar pacotes do PyPI é pip. Esta ferramenta é fornecida com todas as versões modernas do Python.

Em Linux ou MacOS, abra seu terminal e execute o seguinte comando.

$ pip install -U sphinx

No Windows, você deve abrir o Prompt de Comando (⊞Win-r e digitar cmd) e executar o mesmo comando.

C:\> pip install -U sphinx

Após instalação, digitar sphinx-build --version Para saber se tudo funcionou bem, confirme o número da versão instalada do pacote Sphinx.

Instalação a partir de PyPI também permite instalar a última versão ainda em desenvolvimento. Geralmente não é necessário fazer isso, mas pode ser útil para confirmar se ainda há erro na última versão do release estável. Para instalar use o sinalizador --pre.

$ pip install -U --pre sphinx

Usando ambientes virtuais

Ao instalar o Sphinx usando pip, é altamente recomendável usar ambientes virtuais, que isolam os pacotes instalados dos pacotes do sistema, eliminando assim a necessidade de usar privilégios de administrador. Para criar um ambiente virtual no diretório .venv, use o seguinte comando.

$ python -m venv .venv

Ver também

venv – criando ambientes virtuais

Aviso

Observe que em algumas distribuições Linux, como Debian e Ubuntu, isso pode exigir uma etapa de instalação extra, conforme a seguir.

$ apt-get install python3-venv

Docker

Imagens docker para Sphinx são publicadas no Docker Hub. Há dois tipos de imagens:

A primeira é usada para o uso padrão do Sphinx, e a segunda é usada principalmente para construções de PDF usando LaTeX. Escolha uma para o seu propósito.

Nota

sphinxdoc/sphinx-latexpdf contém pacotes TeXLive. Então, a imagem é bem grande (mais de 2GB!).

Dica

Ao usar imagens docker, use o comando docker run para invocar comandos sphinx. Por exemplo, você pode usar o seguinte comando para criar um projeto Sphinx:

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

E você pode usar o seguinte comando para construir o documento HTML:

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

Para obter mais detalhes, leia o arquivo README das imagens do docker.

Instalar a partir dos fontes

Para instalar Sphinx diretamente dos fontes, clone um repositório Git. Isso pode ser feito clonando o repositório e instalando a partir de um clone local, ou simplesmente instalando diretamente a partir do git.

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

Também pode baixar um snapshot do repositório Git em formato tar.gz ou zip. Quando baixado e descompactado esses podem sem instalados com pip como acima.