Instalando Sphinx¶
Visão Geral¶
Sphinx é escrito em `Python`__ e tem suporte ao Python 3.8+. 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 ferramente 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 `package overview`__.
MacPorts¶
Instale python3x-sphinx usando port:
$ sudo port install py38-sphinx
Para configurar os caminhos dos executáveis, use o comando port select:
$ sudo port select --set python python38
$ sudo port select --set sphinx py38-sphinx
Para mais informações, consulte `package overview`__.
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 Guia de Instalação do Hitchhikers para o Python. Você deve instalar o `Python 3`__.
Quando Python estiver instalado, poderá instalar Sphinx usando pip. Consulte pip como instalar abaixo para mais informação.
Instalar a partir do PyPI¶
Os pacotes 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ábel. Para instalar use o flag --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
Você pode ler mais sobre eles no Guia do usuário de empacotamento do Python.
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 repo Git em formato `tar.gz`__ ou `zip`__ . Quando baixado e descompactado esses podem sem instalados com pip como acima.