jump to navigation

Chamando sphinx-build 2011/02/01

Posted by gsavix in ciência colaborativa, civilização, colaboração na aquisição conhecimento, como gerar documentos a partir dos programas fonte, como publicar na internet gratuitamente, Conhecimento, Conhecimento para receber ou transferir tecnologia, Doc, gerador documentos, língua portuguesa, Memorando, metodologia para receber ou transferir conhecimento, publicação jornal internet, publicador documentação, sociologia do conhecimento, Soft.
trackback

Chamando sphinx-build

O script sphinx-build constrói um conjunto Sphinx de documentação. É chamado assim:

$ sphinx-build [opções] diretório-fonte diretório-documentos [arquivos]

onde diretório-fonte é diretório fonte, e and diretório-documentos é o diretório ou pasta onde será construída a documentação. Na maioria das vezes você não precisa especificar arquivos.

O script sphinx-build tem várias opções:

-b nome_do_construtor
É a opção mais importante: pois seleciona o tipo de construção. Os tipos mais comuns são:

html
Páginas HTML. É o construtor padrão.
dirhtml
Páginas HTML, mas um diretório para cada documento. Gera simples URLs (sem .html usado em muitos webserver).
singlehtml
Um único arquivo HTML, com todo o conteúdo.
htmlhelp, qthelp, devhelp, epub
Arquivos HTML, com informações específicas e adicionais para construir coleção de documentação para estes formatos.
latex
Constrói fontes LaTeX, que se compilados podem gerar documento PDF. utiliza para isso o programa pdflatex.
man
Contrói páginas no formato groff (man em sistemas UNIX).
text
Constrói arquivos texto.
doctest
Executa todos os doctests na documentação, se a extensão doctest foi habilitada.
linkcheck
Verifica a integridade de todos links externos.

Veja construtores para uma lista de todos construtores enviados com o Sphinx. Extensões podem adicionar seus próprios construtores.

-a
Se informada, sempre irá gravar todos os tipos de arquivos. O padrão é só gerar saída para arquivos novos ou fontes modificados. (Isto pode não se aplicar a todos os construtores).

-E
Don’t use a saved environment (the structure caching all cross-references), but rebuild it completely. The default is to only read and parse source files that are new or have changed since the last run.

-t alvo
Define o alvo alvo. Isto é relevante para diretivas only que só incluem seu conteúdo se o alvo foi habilitado.

Novo na versão 0.6.

-d caminho
Since Sphinx has to read and parse all source files before it can write an output file, the parsed source files are cached as “doctree pickles”. Normally, these files are put in a directory called .doctrees under the build directory; with this option you can select a different cache directory (the doctrees can be shared between all builders).

-c path
Don’t look for the conf.py in the source directory, but use the given configuration directory instead. Note that various other files and paths given by configuration values are expected to be relative to the configuration directory, so they will have to be present at this location too.

Novo na versão 0.3.

-C
Don’t look for a configuration file; only take options via the -D option.

Novo na versão 0.5.

-D setting=value
Override a configuration value set in the conf.py file. The value must be a string or dictionary value. For the latter, supply the setting name and key like this: -D latex_elements.docclass=scrartcl. For boolean values, use 0 or 1 as the value.

Alterado na versão 0.6: The value can now be a dictionary value.

-A name=value
Make the name assigned to value in the HTML templates.

Novo na versão 0.5.

-n
Run in nit-picky mode. Currently, this generates warnings for all missing references.

-N
Do not emit colored output. (On Windows, colored output is disabled in any case.)

-q
Do not output anything on standard output, only write warnings and errors to standard error.

-Q
Do not output anything on standard output, also suppress warnings. Only errors are written to standard error.

-w arquivo
Grave avisos (warnings e errors) para cada arquivo, em adição ao padrão de erros.

-W
Trate avisos (warnings) como erros. Isto significa que o construtor irá parar ao primeiro erro e o sphinx-build termina com status de saída 1.

-P
(Useful for debugging only.) Run the Python debugger, pdb, if an unhandled exception occurs while building.

You can also give one or more filenames on the command line after the source and build directories. Sphinx will then try to build only these output files (and their dependencies).

Opções do Makefile

Os arquivos Makefile e make.bat são criados pelo programa sphinx-quickstart normalmente executado sphinx-build só com as opções -b e -d. Contudo, são suportadas as seguintes variáveis com suas descrições:

PAPER
O valor para latex_paper_size.

SPHINXBUILD
O comando para usar ao invés de sphinx-build.

BUILDDIR
O diretório onde será construído, ao invés do escolhido pelo sphinx-quickstart.

SPHINXOPTS
Opções adicionais para o programa sphinx-build.

 

© Copyright 2011, Biblioteca Nuto Santana e outros. Criado com Sphinx 1.0.7

Anúncios

Comentários»

No comments yet — be the first.

Deixe uma resposta

Faça o login usando um destes métodos para comentar:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s

%d blogueiros gostam disto: