Utilitários

Sphinx fornece classes e funções utilitárias para desenvolver extensões.

Classes base para componentes

Essas classes base são úteis para permitir que suas extensões obtenham componentes Sphinx (por exemplo, Config, BuildEnvironment e assim por diante) facilmente.

Nota

As subclasses deles podem não funcionar com docutils simples porque estão fortemente acopladas ao Sphinx.

class sphinx.transforms.SphinxTransform(document, startnode=None)

Uma classe base de Transforms.

Comparada com docutils.transforms.Transform, esta classe melhora a acessibilidade às APIs do Sphinx.

property app: Sphinx

Referência ao objeto Sphinx.

property config: Config

Referência ao objeto Config.

property env: BuildEnvironment

Referência ao objeto BuildEnvironment.

class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None)

Uma classe base de pós-transformações.

As pós-transformações são invocadas para modificar o documento e reestruturá-lo para saída. Eles resolvem referências, convertem imagens, fazem transformações especiais para cada formato de saída e assim por diante. Esta classe ajuda a implementar essas pós-transformações.

apply(**kwargs: Any) → None

Substitui para aplicar a transformação à árvore do documentos.

is_supported() → bool

Verifica se esta transformação funcionando para o construtor atual.

run(**kwargs: Any) → None

Método principal de pós-transformações.

As subclasses devem sobrescrever este método em vez de apply().

class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Uma classe base para diretivas Sphinx.

Esta classe fornece métodos auxiliares para diretivas Sphinx.

Adicionado na versão 1.8.

Nota

As subclasses desta classe podem não funcionar com docutils. Esta classe está fortemente acoplada ao Sphinx.

get_location() → str

Obtém informações de localização atuais para registro.

Adicionado na versão 4.2.

get_source_info() → tuple[str | None, int | None]

Obtenha o arquivo fonte e o número da linha.

Adicionado na versão 3.0.

parse_content_to_nodes(allow_section_headings: bool = False) → list[Node]

Analisa o conteúdo da diretiva em nós.

Parâmetros:

allow_section_headings – Os títulos (seções) são permitidos no conteúdo da diretiva? Observe que esta opção ignora as verificações usuais do Docutils na estrutura do doctree, e o uso indevido desta opção pode levar a um doctree incoerente. No Docutils, os nós de seção devem ser apenas filhos dos nós Structural, que incluem os nós document, section e sidebar.

Adicionado na versão 7.4.

parse_inline(text: str, *, lineno: int = -1) → tuple[list[Node], list[system_message]]

Analisa text como elementos em linha.

Parâmetros:

• text – O texto a ser analisado, que deve ser uma única linha ou parágrafo. Não pode conter quaisquer elementos estruturais (títulos, transições, diretivas, etc.).

• lineno – O número da linha onde o texto interpretado começa.

Retorna:

Uma lista de nós (elementos de texto e embutidos) e uma lista de system_messages.

Adicionado na versão 7.4.

parse_text_to_nodes(text: str = '', /, *, offset: int = -1, allow_section_headings: bool = False) → list[Node]

Analisa text em nós.

Parâmetros:

• text – Texto, na forma de string. StringList também é aceito.

• allow_section_headings – Os títulos (seções) são permitidos text? Observe que esta opção ignora as verificações usuais do Docutils na estrutura do doctree, e o uso indevido desta opção pode levar a um doctree incoerente. No Docutils, os nós de seção devem ser apenas filhos dos nós Structural, que incluem os nós document, section e sidebar.

• offset – A posição do conteúdo.

Adicionado na versão 7.4.

set_source_info(node: Node) → None

Define o arquivo fonte e o número da linha para o nó.

Adicionado na versão 2.1.

property config: Config

Referência ao objeto Config.

Adicionado na versão 1.8.

property env: BuildEnvironment

Referência ao objeto BuildEnvironment.

Adicionado na versão 1.8.

class sphinx.util.docutils.SphinxRole

Uma classe base para papéis do Sphinx.

Esta classe fornece métodos auxiliares para papéis do Sphinx.

Adicionado na versão 2.0.

Nota

As subclasses desta classe podem não funcionar com docutils. Esta classe está fortemente acoplada ao Sphinx.

get_location() → str

Obtém informações de localização atuais para registro.

Adicionado na versão 4.2.

property config: Config

Referência ao objeto Config.

Adicionado na versão 2.0.

content: Sequence[str]

Uma lista de strings, o conteúdo da diretiva para personalização (da diretiva “papel”).

property env: BuildEnvironment

Referência ao objeto BuildEnvironment.

Adicionado na versão 2.0.

inliner: Inliner

O objeto docutils.parsers.rst.states.Inliner.

lineno: int

O número da linha onde o texto interpretado começa.

name: str

O nome do papel realmente usado no documento.

options: dict[str, Any]

Um dicionário de opções de diretivas para personalização (da diretiva “papel”).

rawtext: str

Uma string contendo toda a entrada de texto interpretada.

text: str

O conteúdo do texto interpretado

class sphinx.util.docutils.ReferenceRole

Uma classe base para papéis de referência.

Os papéis de referência podem aceitar o estilo título do link <alvo> como texto para o papel. O resultado analisado; o alvo e o título do link serão armazenados em self.título e self.alvo.

Adicionado na versão 2.0.

disabled: bool

Um booleano indica que a referência está desabilitada.

has_explicit_title: bool

Um booleano indica que o papel tem título explícito ou não.

target: str

O alvo do link para o texto interpretado.

title: str

O título do link para o texto interpretado.

class sphinx.transforms.post_transforms.images.ImageConverter(document, startnode=None)

Uma classe base para conversores de imagem.

Um conversor de imagem é uma espécie de módulo de transformação Docutils. Ele é usado para converter arquivos de imagem que não são suportados por um construtor para o formato apropriado para esse construtor.

Por exemplo, construtor LaTeX oferece suporte a PDF, PNG e JPEG como formatos de imagem. No entanto, não oferece suporte a imagens SVG. Nesse caso, o uso de conversores de imagens permite incorporar essas imagens não suportadas no documento. Um dos conversores de imagem; sphinx.ext.imgconverter pode converter uma imagem SVG para o formato PNG usando o Imagemagick internamente.

Existem três etapas para criar seu conversor de imagem personalizado:

1. Faz uma subclasse da classe ImageConverter

2. Substitui conversion_rules, is_available() e convert()

3. Registra seu conversor de imagem no Sphinx usando Sphinx.add_post_transform()

convert(_from: str | PathLike[str], _to: str | PathLike[str]) → bool

Converte um arquivo de imagem para o formato esperado.

_from é o caminho do arquivo de imagem fonte e _to é o caminho do arquivo alvo.

is_available() → bool

Retorna o conversor de imagem está disponível ou não.

available: bool | None = None

O conversor está disponível ou não. Será preenchido na primeira chamada da construção. O resultado é compartilhado no mesmo processo.

conversion_rules: list[tuple[str, str]] = []

Uma regra de conversão suportada pelo conversor de imagem. É representado como uma lista de pares de formato de imagem fonte (mimetype) e alvo um:

conversion_rules = [
    ('image/svg+xml', 'image/png'),
    ('image/gif', 'image/png'),
    ('application/pdf', 'image/png'),
]

default_priority = 200

Prioridade numérica desta transformação, de 0 a 999 (substituição).

Funções unitárias

sphinx.util.parsing.nested_parse_to_nodes(state: RSTState, text: str | StringList, *, source: str = '<generated text>', offset: int = 0, allow_section_headings: bool = True, keep_title_context: bool = False) → list[Node]

Analisa text em nós.

Parâmetros:

• state – O estado da máquina de estado. Deve ser uma subclasse de RSTState.

• text – Texto, na forma de string. StringList também é aceito.

• source – A fonte do texto, usada ao criar uma nova StringList.

• offset – A posição do conteúdo.

• allow_section_headings – Os títulos (seções) são permitidos text? Observe que esta opção ignora as verificações usuais do Docutils na estrutura do doctree, e o uso indevido desta opção pode levar a um doctree incoerente. No Docutils, os nós de seção devem ser apenas filhos dos nós document e section.

• keep_title_context – Se for False (o padrão), então content será analisado como se fosse um documento independente, o que significa que as decorações do título (por exemplo, sublinhados) não precisam corresponder ao documento ao redor. Isso é útil quando o conteúdo analisado vem de um contexto completamente diferente, como docstrings. Se isto for True, então os sublinhados do título deverão corresponder aos do documento adjacente, caso contrário o comportamento será indefinido. Aviso: Até a versão 0.21 do Docutils, as seções com um estilo de decoração correspondente a um nível superior ao nível da seção atual eram descartadas silenciosamente! A partir da versão 0.22.1 do Docutils, um erro é relatado.

Adicionado na versão 7.4.

Tipos de utilitários

class sphinx.util.typing.ExtensionMetadata

Os metadados retornados pela função setup() de uma extensão.

Veja Metadados das extensões.

env_version: int

Um número inteiro que identifica a versão dos dados ambientais adicionados pela extensão.

parallel_read_safe: bool

Indica se a leitura paralela de arquivos fonte é suportada pela extensão.

parallel_write_safe: bool

Indica se a escrita paralela de arquivos de saída é suportada pela extensão (padrão: True).

version: str

A versão da extensão (padrão: 'unknown version').

Previous

API i18n

Next

API de teste