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
. Selanguage
é'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
ou1
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 osphinx-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'
delatex_elements
: isto é,PAPER=a4
configura-a para'a4paper'
ePAPER=letter
para'letterpaper'
.Nota
Uso dessa variável de ambiente parece ter quebrado no Sphinx 1.5, pois
a4
ouletter
acabou como uma opção para documento LaTeX no lugar doa4paper
ouletterpaper
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 sobreFORCE_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 sobreFORCE_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 executarmake html
(Linux/Mac)set PYTHONWARNINGS=
e executarmake html
(Windows)modificar seu Makefile/make.bat e a variável de ambiente
Ver também¶
sphinx-quickstart(1)