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 -W --keep-going

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.

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 o rótulo tag. Isso é relevante para diretivas only que incluem somente seu conteúdo se esse rótulo é definido.

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. 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, --config-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 --config-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 minucioso ou nit-picky, em inglês. 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

Torna avisos em erros. Isso significa que a construção irá ser interrompida ao primeiro aviso e sphinx-build irá terminar e sair com status de saída 1.

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

--keep-going

Com a opção -W, continua processando ao receber avisos até o final da construção, e o sphinx-build sairá com o status de saída 1.

Adicionado na versão 1.8.

-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.

-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)