API de construtor

class sphinx.builders.Builder

Esta é a classe base para todos os construtores.

Ela segue este fluxo de trabalho básico:

Grafo de chamadas para o fluxo de trabalho padrão de construção do Sphinx

Atributos substituíveis

Estes atributos de classe devem ser definidos em subclasses de construtor:

name: ClassVar[str] = ''

O nome do construtor. Este é o valor usado para selecionar construtores na linha de comando.

format: ClassVar[str] = ''

O formato de saída do construtor, ou ‘’ se nenhuma saída de documento for produzida. Esta é geralmente a extensão do arquivo, por exemplo, “html”, embora qualquer valor de string seja aceito. A string de formato do construtor pode ser usada por vários componentes, como SphinxPostTransform ou extensões para determinar sua compatibilidade com o construtor.

epilog: ClassVar[str] = ''

A mensagem emitida após a conclusão bem-sucedida da construção. Esta pode ser uma string de modelo no estilo printf com as seguintes chaves: outdir, project

allow_parallel: ClassVar[bool] = False

Se é seguro fazer chamadas paralelas de write_doc().

supported_image_types: ClassVar[list[str]] = []

A lista de tipos MIME de formatos de imagem suportados pelo construtor. Os arquivos de imagem são pesquisados ​​na ordem em que aparecem aqui.

supported_remote_images: ClassVar[bool] = False

O construtor pode produzir documentos de saída que podem buscar imagens externas quando abertos.

supported_data_uri_images: ClassVar[bool] = False

O formato de arquivo produzido pelo construtor permite que imagens sejam incorporadas usando URIs de dados.

default_translator_class: ClassVar[type[nodes.NodeVisitor]]

Classe tradutora padrão para o construtor. Isso pode ser substituído por set_translator().

Métodos principais

Estes métodos definem o fluxo principal de construção e devem ser substituídos:

final build_all() → None

Constrói todos os arquivos fonte.

final build_specific(filenames: Sequence[Path]) → None

Reconstrói apenas o necessário para alterações nos filename.

final build_update() → None

Reconstrói apenas o que foi alterado ou adicionado desde a última construção.

final build(docnames: Iterable[str] | None, summary: str | None = None, method: Literal['all', 'specific', 'update'] = 'update') → None

Método de construção principal, geralmente chamado por um método build_* específico.

Primeiro atualiza o ambiente e depois chama write().

final read() → list[str]

(Re-)lê todos os arquivos novos ou alterados desde a última atualização.

Armazena todos os docnames do ambiente no formato canônico (ou seja, usando SEP como separador no lugar de os.path.sep).

final read_doc(docname: str, *, _cache: bool = True) → None

Analisa um arquivo e adiciona/atualiza entradas de inventário para a doctree.

final write_doctree(docname: str, doctree: document, *, _cache: bool = True) → None

Escreve a doctree em um arquivo, para ser usado como cache nas reconstruções.

final write(build_docnames: Iterable[str] | None, updated_docnames: Iterable[str], method: Literal['all', 'specific', 'update'] = 'update') → None

Escreve arquivos de saída específicos do construtor.

Métodos abstratos

Estes devem ser implementados em subclasses de construtor:

get_outdated_docs() → str | Iterable[str]

Retorna um iterável de arquivos de saída desatualizados ou uma string descrevendo o que uma construção de atualização construir.

Se o construtor não gerar arquivos individuais correspondentes aos arquivos fonte, retorna uma string aqui. Em caso afirmativo, retorna um iterável dos arquivos que precisam ser escritos.

write_doc(docname: str, doctree: document) → None

Escreve o arquivo de saída para o documento

Parâmetros:

• docname – o docname.

• doctree – define o conteúdo a ser escrito.

O nome do arquivo de saída deve ser determinado dentro deste método, normalmente chamando get_target_uri() ou get_relative_uri().

get_target_uri(docname: str, typ: str | None = None) → str

Retorna o URI alvo para um nome do documento.

typ pode ser usado para qualificar a característica do link para construtores individuais.

Métodos substituíveis

Esses métodos podem ser substituídos nas subclasses do construtor:

init() → None

Carrega os modelos necessários e executa a inicialização. A implementação padrão não faz nada.

write_documents(docnames: Set[str]) → None

Escreve todos documentos em docnames.

Este método pode ser substituído se um construtor não cria arquivos de saída para cada documento.

prepare_writing(docnames: Set[str]) → None

Um lugar onde você pode adicionar lógica antes de write_doc() ser executado

copy_assets() → None

Para onde os ativos (imagens, arquivos estáticos, etc) são copiados antes da escrita

get_relative_uri(from_: str, to: str, typ: str | None = None) → str

Retorna um URI relativo entre dois nomes de arquivos fonte.

levanta:

NoUri se não houver como retornar um URI sensato.

finish() → None

Conclui o processo de construção.

A implementação padrão não faz nada.

Atributos

Atributos que são chamáveis a partir da instância do construtor:

events

Um objeto EventManager.

Atributos substituíveis (extensões)

As subclasses de Builder podem definir esses atributos para oferecer suporte a extensões embutidas:

supported_linkcode: str

Por padrão, a extensão linkcode injetará apenas referências para um construtor html. O atributo de classe supported_linkcode pode ser definido em um construtor não HTML para dar suporte ao gerenciamento de referências geradas pelo linkcode. O valor esperado para esse atributo é uma expressão compatível com only.

Por exemplo, se um construtor foi nomeado custom-builder, o seguinte pode ser usado:

class CustomBuilder(Builder):
    supported_linkcode = 'custom-builder'
    ...

Previous

API de ambiente de construção

Next

API de gerenciador de eventos