sphinx-build

Sinopse

sphinx-build [opções] <sourcedir> <outputdir> [nomes de arquivos …]

Descrição

sphinx-build gera documentação dos arquivos que estão em <sourcedir> e monta documento final em <outputdir>.

sphinx-build busca no <sourcedir>/conf.py por um arquivo de configurações. sphinx-quickstart(1) pode ser usado para gerar modelos de arquivos, inclusive o arquivo conf.py.

sphinx-build pode criar documentação em diversos formatos. Um formato é selecionado especificando o nome do construtor na linha de comando; o padrão é HTML. Esses construtores também pode executar outras tarefas relacionadas ao processamento da documentação. Para uma lista de construtores disponíveis, consulte Construtores.

Por padrão tudo que estiver desatualizado é reconstruído. Saída de apenas alguns arquivos pode ser construída através da especificação individual desses arquivos.

Opções

-M buildername

Seleciona um construtor, usando o make-mode. Veja Construtores para uma lista de todos os construtores embutidos do Sphinx. As extensões podem adicionar seus próprios construtores.

Importante

O Sphinx só reconhece a opção -M se ela for usada primeiro, junto com os diretórios fonte e de saída, antes de qualquer outra opção ser passada. Por exemplo:

sphinx-build -M html ./source ./build --fail-on-warning

O make-mode fornece a mesma funcionalidade de construção que um Makefile ou Make.bat padrão e fornece os seguintes pipelines de construção adicionais:

latexpdf

Constrói arquivos LaTeX e executa cada um deles através do pdflatex ou através da configuração latex_engine. Se language é 'ja', irá usar automaticamente pipeline latex platex/dvipdfmx para PDF.

info

Constrói arquivos Texinfo e executa cada um através de makeinfo.

help

Mostra uma lista de alvos de construtores válidos e sai.

Nota

Os locais padrão do diretório de saída ao usar make-mode diferem dos padrões ao usar -b.

• doctrees são salvos em <outputdir>/doctrees

• arquivos de saída são salvos em <outputdir>/<builder name>

Adicionado na versão 1.2.1.

-b buildername, --builder buildername

Seleciona um construtor.

Veja Construtores para uma lista de todos os construtores embutidos do Sphinx. As extensões podem adicionar seus próprios construtores.

Alterado na versão 7.3: Adiciona a opção longa --builder.

-a, --write-all

Se passado, sempre sobrepõe a gravação de todos arquivos. O padrão é sobrepor somente arquivos de saída para novos e modificados. (isso não se aplica a todos construtores).

Nota

Esta opção não relê os arquivos fonte. Para ler e reprocessar cada arquivo, use --fresh-env.

Alterado na versão 7.3: Adiciona a opção longa --write-all.

-E, --fresh-env

Não usa o ambiente salvo (a estrutura faz cache das referências cruzadas), mas reconstruir completamente. O padrão é só ler e fazer parse dos arquivos fonte que forem novos ou foram atualizados desde a última execução.

Alterado na versão 7.3: Adiciona a opção longa --fresh-env.

-t tag, --tag tag

Define a tag tag. Isto é relevante para diretivas only que incluem seu conteúdo apenas se certas tags estiverem definidas. Veja incluindo conteúdo com base nas tags para mais detalhes.

Adicionado na versão 0.6.

Alterado na versão 7.3: Adiciona a opção longa --tag.

-d path, --doctree-dir path

Sphinx leu e fez parse de todos fontes antes de gravar saída nos arquivos, esses arquivos fontes são mantidos em cache como “doctree pickles”. Normalmente, esses arquivos são gravados em um diretório chamado .doctrees sob o diretório onde está sendo feito o build; com essa opção pode ser selecionado um diretório cache diferente (doctrees podem ser compartilhados entre vários construtores).

Alterado na versão 7.3: Adiciona a opção longa --doctree-dir.

-j N, --jobs N

Distribui a construção através de N processos em paralelo, para permitir o processo de construção em máquinas com múltiplos processadores ser mais efetivo. Este recurso só funciona em sistemas que têm suporte a “fork”. o Windows não é suportado. Note que nem todas as partes nem todos os construtores do Sphinx podem ser executados em paralelo. Se o argumento auto é fornecido, então o Sphinx usa o número de CPUs como N. O padrão é 1.

Adicionado na versão 1.2: Esta opção deve ser considerada como experimental.

Alterado na versão 1.7: Suporte ao argumento auto.

Alterado na versão 6.2: Adiciona a opção longa --jobs.

-c path, --conf-dir path

Não procura pelo conf.py no diretório fonte, mas use o diretório de configuração informado. Note que outros arquivos e caminhos obtidos pelos valores da configuração são esperados como relativos ao diretório de configuração, portanto também devem estar presentes nessa localização.

Adicionado na versão 0.3.

Alterado na versão 7.3: Adiciona a opção longa --conf-dir.

-C, --isolated

Não usa um arquivo de configuração; obtém as opções por meio da opção --define.

Adicionado na versão 0.5.

Alterado na versão 7.3: Adiciona a opção longa --isolated.

-D setting=value, --define setting=value

substitui um valor da configuração definido no arquivo conf.py. O valor deve ser número, string, lista ou dicionário.

Para listas, pode-se separar os elementos por vírgulas como esse: -D html_tema_caminho=caminho1,caminho2.

Para valores dicionário, forneça o nome opção e a chave como -D latex_elements.docclass=scrartcl.

Para valores booleanos, use 0 ou 1 como valor.

Alterado na versão 0.6: O valor pode ser um valor de dicionário.

Alterado na versão 1.3: O valor pode ser um valor de lista.

Alterado na versão 7.3: Adiciona a opção longa --define.

-A name=value, --html-define name=value

Torna o name assinalado para value nos modelos HTML.

Adicionado na versão 0.5.

Alterado na versão 7.3: Adiciona a opção longa --html-define.

-n, --nitpicky

Executa no modo nitpicky (em português, minucioso). Atualmente, isso gera avisos para todas as referências inexistentes. Veja o valor de configuração nitpick_ignore para uma forma de não exibir referências conhecidas como “sabidamente ausentes”.

Alterado na versão 7.3: Adiciona a opção longa --nitpicky.

-N, --no-color

Não emite saída colorida.

Alterado na versão 1.6: Adiciona a opção longa --no-color.

--color

Emite saída colorida. Detectado automaticamente por padrão.

Adicionado na versão 1.6.

-v, --verbose

Incrementa a verbosidade (log-level). Essa opção pode ser dada até três vezes mais para maior detalhe de log na saída. Isso implica -T.

Adicionado na versão 1.2.

Alterado na versão 7.3: Adiciona a opção longa --verbose.

-q, --quiet

Não emite saída nenhuma na saída padrão, só grava avisos de erros na saída padrão de erros.

Alterado na versão 7.3: Adiciona a opção longa --quiet.

-Q, --silent

Não emite nenhuma saída na saída padrão, também suprime avisos. Só erros serão exibidos na saída padrão de erros.

Alterado na versão 7.3: Adiciona a opção longa --silent.

-w file, --warning-file file

Grava avisos (e erros) para um determinado arquivo, em adição à saída de erro padrão.

Alterado na versão 7.3: As sequências de controle ANSI são removidas ao gravar em file.

Alterado na versão 7.3: Adiciona a opção longa --warning-file.

-W, --fail-on-warning

Transforma avisos em erros. Isso significa que sphinx-build sai com status de saída 1 se quaisquer avisos forem gerados durante a construção.

Alterado na versão 7.3: Adiciona a opção longa --fail-on-warning.

Alterado na versão 8.1: sphinx-build não sai mais no primeiro aviso, mas em vez disso executa a construção inteira e sai com status de saída 1 se algum aviso foi gerado. Esse comportamento era habilitado anteriormente com --keep-going.

--keep-going

A partir do Sphinx 8.1, --keep-going está sempre habilitado. Anteriormente, ele era aplicável somente ao usar --fail-on-warning, que por padrão saía de sphinx-build no primeiro aviso. Usar --keep-going executa sphinx-build até a conclusão e sai com status de saída 1 se erros forem encontrados.

Adicionado na versão 1.8.

Alterado na versão 8.1: sphinx-build não mais é encerrado no primeiro aviso, o que significa que, na verdade, --keep-going está sempre habilitado. A opção é mantida para compatibilidade, mas pode ser removida em alguma data posterior.

-T, --show-traceback

Exibe rastreabilidade completa quando uma exceção não tratada ocorrer. Caso contrário, só um resumo será exibido e a informação do rastreamento será salva em arquivo para análise posterior.

Adicionado na versão 1.2.

Alterado na versão 7.3: Adiciona a opção longa --show-traceback.

-P, --pdb

(Útil só para depuração). Executar o depurador do Python, pdb, se uma exceção não tratada ocorrer durante a construção.

Alterado na versão 7.3: Adiciona a opção longa --pdb.

--exception-on-warning

Levanta uma exceção quando um aviso for emitido durante a construção. Isso pode ser útil em combinação com --pdb para depurar avisos.

Adicionado na versão 8.1.

-h, --help, --version

Exibe resumo de uso ou versão do Sphinx.

Adicionado na versão 1.2.

Também pode ser informado um ou mais nomes de arquivo na linha de comando após o diretório fonte e o de montagem. Sphinx irá tentar construir esses arquivos de saída (bem como suas dependências).

variáveis de ambiente

O sphinx-build usa as seguintes variáveis de ambiente:

MAKE

O caminho para o comando make. O nome do comando também é permitido. sphinx-build usa isso para chamar processos dependentes para montador no modo make.

Opções de Makefile

Os arquivos Makefile e make.bat criados pelo sphinx-quickstart normalmente executam sphinx-build só com a opção -b e -d. Contudo oferecem suporte às seguintes variáveis para personalizar o comportamento:

PAPER

Isso configura a chave 'papersize' de latex_elements: isto é, PAPER=a4 configura-a para 'a4paper' e PAPER=letter para 'letterpaper'.

Nota

Uso dessa variável de ambiente parece ter quebrado no Sphinx 1.5, pois a4 ou letter acabou como uma opção para documento LaTeX no lugar do a4paper ou letterpaper necessários, respectivamente. Corrigido em 1.7.7.

SPHINXBUILD

O comando para usar em vez de sphinx-build.

BUILDDIR

O diretório onde será construído em vez de um escolhido pelo sphinx-quickstart.

SPHINXOPTS

Opções adicionais para sphinx-build. Essas opções também podem ser definidas por meio da variável de atalho O (‘o’ maiúsculo).

NO_COLOR

Quando definido (independentemente do valor), sphinx-build não usará cores na saída do terminal. NO_COLOR tem precedência sobre FORCE_COLOR. Veja no-color.org para outras bibliotecas que oferecem suporte a este padrão da comunidade.

Adicionado na versão 4.5.0.

FORCE_COLOR

Quando definido (independentemente do valor), sphinx-build usará cores na saída do terminal. NO_COLOR tem precedência sobre FORCE_COLOR.

Adicionado na versão 4.5.0.

Avisos de Obsoleto

Se qualquer aviso como RemovedInSphinxXXXWarning for exibido quando for construir o documento, e algumas extensões Sphinx estiverem referenciando funcionalidades tornadas obsoletas. Nesse caso favor entrar em contato com o autor da extensão.

Para desabilitar avisos de obsoleto, favor ver variável de ambiente PYTHONWARNINGS=. Por exemplo:

• PYTHONWARNINGS= make html (Linux/Mac)

• export PYTHONWARNINGS= e executar make html (Linux/Mac)

• set PYTHONWARNINGS= e executar make html (Windows)

• modificar seu Makefile/make.bat e a variável de ambiente

Ver também

sphinx-quickstart(1)

Previous

sphinx-quickstart

Next

sphinx-apidoc