Instalando Sphinx¶
Sphinx é uma aplicação Python. Ele pode ser instalado de uma das maneiras descritas abaixo.
Após a instalação, você pode verificar se o Sphinx está disponível executando
$ sphinx-build --version
Isso deve imprimir o número da versão do Sphinx.
Dica
Para desenvolvimento local, geralmente é recomendado instalar o Sphinx em um ambiente não global (usando, por exemplo, ambientes venv ou conda). Isso permitirá o uso de versões separadas do Sphinx e extensões de terceiros para cada projeto do Sphinx.
Pacote PyPI¶
Os pacotes Sphinx são publicados no Python Package Index (PyPI). A ferramenta preferida para instalar pacotes do PyPI é pip, que está incluída em todas as versões modernas do Python.
Execute o seguinte comando:
$ pip install -U sphinx
Dica
Para evitar problemas ao reconstruir seu ambiente, é aconselhável fixar versões do sphinx e de extensões de terceiros em um arquivo requirements.txt:
$ pip install -r requirements.txt
Ou, se estiver escrevendo documentação para um pacote Python, coloque as dependências no arquivo pyproject.toml:
$ pip install . --group docs
Pacote conda¶
Para trabalhar com conda, você precisa de uma distribuição Python baseada em conda como anaconda, miniconda, miniforge ou micromamba.
O Sphinx está disponível através do canal anaconda principal (mantido pela Anaconda Inc.)
$ conda install sphinx
bem como através do canal da comunidade conda-forge
$ conda install -c conda-forge sphinx
Gerenciador de pacotes específico do sistema operacional¶
Você pode instalar uma versão global do Sphinx em seu sistema usando gerenciadores de pacotes específicos do sistema operacional. No entanto, esteja ciente de que isso é menos flexível e você poderá enfrentar problemas de compatibilidade se quiser trabalhar em projetos diferentes.
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¶
Sphinx pode ser instalado usando Homebrew, MacPorts.
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 py314-sphinx
Para configurar os caminhos dos executáveis, use o comando port select:
$ sudo port select --set python python314
$ sudo port select --set sphinx py314-sphinx
Para mais informações, consulte a visão geral do pacote.
Windows¶
Sphinx pode ser instalado usando Chocolatey.
Chocolatey¶
$ choco install sphinx
Você precisaria instalar Chocolatey antes de executar isso.
Para mais informações, consulte a página do chocolatey.
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.
Instalação da versão de desenvolvimento mais recente¶
Você pode instalar o desenvolvimento mais recente do PyPI usando o sinalizador --pre:
$ pip install -U --pre sphinx
Aviso
Geralmente você não precisará (ou desejará) fazer isso, mas pode ser útil se você encontrar um possível bug na versão estável mais recente.
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.