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

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

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

This is an HTML builder that combines the whole project in one output file. (Obviously this only works with smaller projects.) The file is named like the root document. No indices will be generated.

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

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

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

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

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

Esse construtor produz a mesma saida do construtor HTML e também gera arquivos epub para leitores de ebook readers. Ver Informações de epub 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

This builder produces LaTeX source files in the output directory. The actual PDF builds happen inside this output directory and need to be triggered in a second step. This can be done via make all-pdf there. To combine the two steps into only one, use sphinx-build -M (i.e. -M latexpdf not -b latexpdf) or make latexpdf at the project root.

See latex_documents and the chapter Opções para saída LaTeX for available options.

PDF builds need a sufficiently complete LaTeX installation. The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS, whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04, but PDF builds can be successfully done on much older LaTeX installations.

At any rate, on Ubuntu for example, following packages must all be present:

• texlive-latex-recommended

• texlive-fonts-recommended

• tex-gyre (if latex_engine left to default)

• texlive-latex-extra

• latexmk

Alterado na versão 4.0.0: TeX Gyre fonts now required for 'pdflatex' engine (default).

Additional packages are needed in some circumstances:

• texlive-lang-cyrillic for Cyrillic (and also then cm-super if using the default fonts),

• texlive-lang-greek for Greek (and also then cm-super if using the default fonts),

• texlive-xetex if latex_engine is 'xelatex',

• texlive-luatex if latex_engine is 'lualatex',

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

Nota

Since 1.6, make latexpdf uses on GNU/Linux and macOS latexmk, as it makes sure the needed number of runs is automatically executed. On Windows the PDF builds execute a fix number of LaTeX runs (three, then makeindex, then two more).

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

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

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

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 Informações de Texinfo 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

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

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

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

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

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

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

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

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

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:

• doctest

• coverage

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.