Builders

These are the built-in Sphinx builders. More builders can be added by extensions.

O “nome” do construtor deve ser informado na linha de comando na opção -b do programa:sphinx-build para escolher o construtor.

class sphinx.builders.html.StandaloneHTMLBuilder[código fonte]

HTML Esse é o construtor padrão. A saída será no diretório de arquivos HTML, completo com as folhas de estilo e opcionalmente com os fontes reST. Existem alguns valores para configuráveis para personalizar a saída desse construtor, ver o capítulo Opções para saída HTML para detalhes.

name = 'html'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinx.builders.dirhtml.DirectoryHTMLBuilder[código fonte]

Essa é uma subclasse do construtor HTML. Sua saída é no diretorio de arquivos HTML, onde cada arquivo é nomeado index.html e colocado em um subdiretório igual ao nome da página. Por exemplo, o documento markup/rest.rst não resultará em um arquivo de saída markup/rest.html, mas sim em markup/rest/index.html. Quando gerando links entre páginas, o index.html é omitido, a URL será algo como markup/rest/.

name = 'dirhtml'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 0.6.

class sphinx.builders.singlehtml.SingleFileHTMLBuilder[código fonte]

Esse é um construtor HTML que combina todo o projeto em um único arquivo de saída, (obviamente isso só funciona em pequenos projetos). O arquivo será nomeado como documento principal. Nenhum índice será gerado.

name = 'singlehtml'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 1.0.

class sphinxcontrib.htmlhelp.HTMLHelpBuilder[código fonte]

Esse construtor produz a mesma saída do construtor HTML, mas também gerá arquivos de Ajuda HTML, que permitem ao Microsoft Ajuda HTML Workshop compilá-los em um arquivo CHM.

name = 'htmlhelp'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinxcontrib.qthelp.QtHelpBuilder[código fonte]

Esse construtor produz a mesma saída que o construtor HTML e gera também coleção de arquivos Qt help que permite ao gerador Qt compilá-los.

Alterado na versão 2.0: Moved to sphinxcontrib.qthelp from sphinx.builders package.

name = 'qthelp'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinxcontrib.applehelp.AppleHelpBuilder[código fonte]

Esse construtor produz um Livro Help Apple baseado na mesma saída do construtor HTML.

Se o diretório fonte contiver alguma pasta .lproj, então o idioma correspondente será combinado com a saída gerada. Essas pastas serão ignoradas por todos os outros tipos de documentação.

Para gerar um livro de ajuda válido, esse construtor requer o uso da ferramenta de linha de comando hiutil, o qual só está disponível no Mac OS X 10.6 ou versão posterior. O passo da indexação pode ser desabilitado com a configuração True applehelp_disable_external_tools e nesse caso a saída não será válida até o término do hiutil.

name = 'applehelp'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/png', 'image/gif', 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 1.3.

Alterado na versão 2.0: Moved to sphinxcontrib.applehelp from sphinx.builders package.

class sphinxcontrib.devhelp.DevhelpBuilder[código fonte]

Esse construtor produz a mesma saida que o construtor HTML e também gera arquivos de suporte GNOME Devhelp o que permite que o leitor GNOME Devhelp possa visualizá-los.

name = 'devhelp'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Alterado na versão 2.0: Moved to sphinxcontrib.devhelp from sphinx.builders package.

class sphinx.builders.epub3.Epub3Builder[código fonte]

Esse construtor produz a mesma saida do construtor HTML e também gera arquivos epub para leitores de ebook readers. Ver Epub info para detalhes sobre isso. Para definições do formato epub, veja http://idpf.org/epub ou https://en.wikipedia.org/wiki/EPUB. O construtor cria arquivos EPUB 3.

name = 'epub'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 1.4.

Alterado na versão 1.5: Desde Sphinx-1.5, o construtor epub3 é usado para o construtor de epub.

class sphinx.builders.latex.LaTeXBuilder[código fonte]

Esse construtor produz um conjunto de arquivos LaTeX no diretório de saída. É necessário especificar quais documentos serão incluídos em quais arquivos LaTeX através do opção de configuração latex_documents. Existem algumas configurações que personalizam a saída desse construtor, para detalhes veja o capítulo Opções para saída LaTeX.

The produced LaTeX file uses several LaTeX packages that may not be present in a “minimal” TeX distribution installation.

On Ubuntu xenial, the following packages need to be installed for successful PDF builds:

  • texlive-latex-recommended

  • texlive-fonts-recommended

  • tex-gyre (if latex_engine is 'pdflatex')

  • texlive-latex-extra

  • latexmk (this is a Sphinx requirement on GNU/Linux and MacOS X for functioning of make latexpdf)

Additional packages are needed in some circumstances (see the discussion of the 'fontpkg' key of latex_elements for more information):

  • texlive-lang-cyrillic for Cyrillic (even individual letters), and, cm-super or cm-super-minimal (if default fonts),

  • texlive-lang-greek for Greek (even individual letters), and, cm-super or cm-super-minimal (if default fonts),

  • texlive-xetex if latex_engine is 'xelatex',

  • texlive-luatex if latex_engine is 'lualatex',

  • fonts-freefont-otf if latex_engine is 'xelatex' or 'lualatex'.

The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX distribution is based on a TeXLive 2015 snapshot dated March 2016.

Alterado na versão 1.6: Formalmente testado funcionou no Ubuntu precise (TeXLive 2009).

Alterado na versão 2.0: Formerly, testing had been done on Ubuntu trusty (TeXLive 2013).

Alterado na versão 4.0.0: TeX Gyre fonts dependency for the default LaTeX font configuration.

Nota

Desde 1.6, make latexpdf usa latexmk (não no Windows).

Podem ser passadas ao latexmk opções via LATEXMKOPTS variável Makefile. Por exemplo:

make latexpdf LATEXMKOPTS="-silent"

reduz saída na console ao mínimo.

Also, if latexmk is at version 4.52b or higher (January 2017) LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in case of numerous graphics inclusions.

To pass options directly to the (pdf|xe|lua)latex binary, use variable LATEXOPTS, for example:

make latexpdf LATEXOPTS="--halt-on-error"
name = 'latex'

The builder’s name, for the -b command line option.

format = 'latex'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['application/pdf', 'image/png', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Observe que um construtor do dicrect PDF está sendo fornecido por rinohtype. O nome do construtor é rinho. Consulte o manual do rinohtype para detalhes.

class sphinx.builders.text.TextBuilder[código fonte]

Esse construtor produz um arquivo texto para cada arquivo reST – e é exatamente o mesmo que a fonte reST, mas sem as marcações que são suprimidas para melhor legibilidade.

name = 'text'

The builder’s name, for the -b command line option.

format = 'text'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 0.4.

class sphinx.builders.manpage.ManualPageBuilder[código fonte]

Esse construtor produz páginas de manual no formato groff. Especificar quais documentos serão incluídos em quais páginas de manual através do valor de configuração man_pages.

name = 'man'

The builder’s name, for the -b command line option.

format = 'man'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 1.0.

class sphinx.builders.texinfo.TexinfoBuilder[código fonte]

Esse construtorproduz arquivos Texinfo que podem ser processados em arquivos Info através do makeinfo. Especificar quais documentos serão incluídosem quais arquivos Texinfo através do valor de configuração texinfo_documents.

Formato Info é a base da ajuda on-line usado por GNU Emacs e por programas baseados em termina info. Ver Texinfo info para mais detalhes. O formato Texinfo é o sistema de documentação usado pelo projeto GNU. Mais informação sobre Texinfo pode ser encontrado em https://www.gnu.org/software/texinfo/.

name = 'texinfo'

The builder’s name, for the -b command line option.

format = 'texinfo'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/png', 'image/jpeg', 'image/gif']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 1.1.

class sphinxcontrib.serializinghtml.SerializingHTMLBuilder[código fonte]

Esse construtor usa um módulo que implementa serialização Python API (pickle, simplejson, phpserialize, e outros) para dump da documentação HTML gerada. O construtor pickle é uma subclasse desse construtor.

O formato de uma subclasse concreta desse construtor de serialização para PHP serialization aparenta:

import phpserialize

class PHPSerializedBuilder(SerializingHTMLBuilder):
    name = 'phpserialized'
    implementation = phpserialize
    out_suffix = '.file.phpdump'
    globalcontext_filename = 'globalcontext.phpdump'
    searchindex_filename = 'searchindex.phpdump'
implementation

O módulo que implementa funções dump(), load(), dumps() e loads() em acordo com funções com o mesmo nome do módulo usado. Módulos conhecidos que implementam essa interface são simplejson, phpserialize, plistlib e outros.

out_suffix

O sufixo para todos arquivos padrão.

globalcontext_filename

O nome do arquivo que contém a “contexto global”. Essa é uma configuração dicionário com alguns valores como nome do projeto.

searchindex_filename

O nome do arquivo para índice de busca que o Sphinx irá criar.

Ver Detalhes Construtor de Serialização para detalhes sobre formato de saída.

Novo na versão 0.5.

class sphinxcontrib.serializinghtml.PickleHTMLBuilder[código fonte]

Esse construtor produz um diretório com arquivos com fragmentos de HTML e informações TOC tabela de conteúdo, para uso pela aplicação web (ou ferramenta personalizada pós processamento) que não utiliza modelos HTML padrão.

Ver Detalhes Construtor de Serialização para detalhes sobre formato de saída.

name = 'pickle'

The builder’s name, for the -b command line option.

O antigo nome web também continua funcionando.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

O sufixo do arquivo é .fpickle. O contexto global é chamado globalcontext.pickle, o índice pesquisa searchindex.pickle.

class sphinxcontrib.serializinghtml.JSONHTMLBuilder[código fonte]

Esse construtor produz um diretório com arquivos JSON contendo maioria das informações HTML e TOC tabela de conteúdo, para uso da aplicação web (ou ferramenta de pós processamento) que não utilize modelos HTML padrão.

Ver Detalhes Construtor de Serialização para detalhes sobre formato de saída.

name = 'json'

The builder’s name, for the -b command line option.

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

O sufixo do arquivo é .fjson. O contexto global é chamado globalcontext.json``e o índice de busca ``searchindex.json.

Novo na versão 0.5.

class sphinx.builders.gettext.MessageCatalogBuilder[código fonte]

Esse construtor produz catálogos de mensagem estilo gettext. Cada arquivo de topo de nível ou subdiretório gera um simples catálogo padrão .pot.

Para referências adicionais ver a documentação Internacionalização

name = 'gettext'

The builder’s name, for the -b command line option.

format = ''

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 1.1.

class sphinx.builders.changes.ChangesBuilder[código fonte]

Esse construtor produz um HTML das diretivas com todas adições versionadded, modificações versionchanged e obsolescências deprecated. É util para gerar um arquivo ChangeLog por exemplo.

name = 'changes'

The builder’s name, for the -b command line option.

format = ''

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

class sphinx.builders.dummy.DummyBuilder[código fonte]

Esse construtor não produz saída. A entra é passada e verificada só para consistência. Isso é útil para diversos propósitos.

name = 'dummy'

The builder’s name, for the -b command line option.

supported_image_types: List[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 1.4.

class sphinx.builders.linkcheck.CheckExternalLinksBuilder[código fonte]

Esses construtores buscam em todos os documentos para ligações externas, tenta abrir esses links com requests, e grava uma visão com os inconsistentes e redireciona para a saída padrão e para output.txt no diretório de saída.

name = 'linkcheck'

The builder’s name, for the -b command line option.

format = ''

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Alterado na versão 1.5: Desde Sphinx-1.5, o modulo do construtor linkcheck está disponível.

Alterado na versão 3.4: The linkcheck builder retries links when servers apply rate limits.

class sphinx.builders.xml.XMLBuilder[código fonte]

Esse construtor produz arquivos XML nativos Docutils. A saída pode ser transformada com ferramentas XML padrão como processadores XSLT em formulários prontos arbitrários.

name = 'xml'

The builder’s name, for the -b command line option.

format = 'xml'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 1.2.

class sphinx.builders.xml.PseudoXMLBuilder[código fonte]

Esse construtor é usado para depuração do Sphinx/Docutils na linha “Leitor para Transformador para Escritor”. Produz arquivos de counteúdo formatado “pseudo-XML”, aninhados por identação (sem marcas finais). Atributos externos para todos elementos são criados bem como atributos internos para qualquer pendência de elemento, também é dada.

name = 'pseudoxml'

The builder’s name, for the -b command line option.

format = 'pseudoxml'

The builder’s output format, or ‘’ if no document output is produced.

supported_image_types: List[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Novo na versão 1.2.

Extensões Internas do Sphinx que oferecem mais construtores são:

Detalhes Construtor de Serialização

Todos os construtores de serialização produzem saída em um arquivo para cada arquivo fonte e alguns arquivos especiais. Também são copiados os arquivos fonte reST do diretório _sources para o diretório de saída.

A PickleHTMLBuilder é uma subclasse implícita que implementa o interface de serialização.

Os arquivos dos fontes tem extensão out_suffix, e são arranjados em diretórios como estão os arquivos fonte. São desconstruídos para um dicionário (ou estrutura similar a um dicionário) com essas chaves:

body

O “corpo” HTML (que é o HTML renderizado do arquivo fonte), como renderizado pelo tradutor HTML.

title

O título do documento, como HTML (pode conter marcas).

toc

Tabela de conteúdo do arquivo ou sumário, renderizado como HTML <ul>.

display_toc

Um booleano que é True se o toc contém mais que uma entrada.

current_page_name

Nome do documento corrente do arquivo corrente.

parents, prev and next

Informação sobre os capítulos relacionados com a árvore do TOC. Cada relação é um dicionario com as chaves link (HREF da relação) e title (título do documento relacionado, como HTML). parents é a lista de relações, enquanto prev e next são relações simples.

sourcename

O nome do arquivo fonte sob _sources.

Arquivos especiais localizados na raiz do diretório. São eles:

SerializingHTMLBuilder.globalcontext_filename

Um dicionário montado com as seguintes chaves:

project, copyright, release, version

Os mesmos valores informados no arquivo de configuração.

style

html_style.

last_updated

Data da última construção.

builder

Nome do construtor usado, no caso de montagens será sempre 'pickle'.

titles

Um dicionário com todos os títulos de documentos, como strings HTML.

SerializingHTMLBuilder.searchindex_filename

Um índice que pode ser usado para busca nos documentos. É uma lista com estas entradas:

  • Lista de nomes de documentos indexados.

  • Uma lista de títulos de documentos, como strings HTML, na mesma ordem da primeira lista.

  • Dicionário mapeando palavras raízes (processadas por tratamento idioma Inglês) para uma lista de inteiros, os quais possuem índices na primeira lista.

environment.pickle

O ambiente do construtor. Sempre é um arquivo pickle, independentemente do construtor e uma cópia do ambiente usado quando o construtor foi iniciado.

Por fazer

Membros comuns do documento.

Diferentemente de outros arquivos pickle, esse arquivo requer que o pacote sphinx esteja disponível no processo.