API de marcações do Docutils¶

Esta seção descreve a API para adicionar elementos de marcação reStructuredText (papéis e diretivas).

Papéis¶

Os papéis seguem a interface descrita abaixo. Eles devem ser registrados por uma extensão usando Sphinx.add_role() ou Sphinx.add_role_to_domain().

def role_function(
    role_name: str, raw_source: str, text: str,
    lineno: int, inliner: Inliner,
    options: dict = {}, content: list = [],
) -> tuple[list[Node], list[system_message]]:
    elements = []
    messages = []
    return elements, messages

Os parâmetros options e content são usados apenas para papéis personalizados criados através da diretiva role. O valor de retorno é uma tupla de duas listas, a primeira contendo os nós de texto e os elementos do papel, e a segunda contendo quaisquer mensagens do sistema geradas. Para obter mais informações, consulte a visão geral de papel personalizado do Docutils.

Criando papéis personalizados¶

O Sphinx fornece duas classes base para a criação de papéis personalizados, SphinxRole e ReferenceRole.

Eles fornecem uma interface baseada em classes para criação de papéis, onde a lógica principal deve ser implementada em seu método run(). As classes fornecem vários métodos e atributos úteis, como self.text, self.config e self.env. A classe ReferenceRole implementa a lógica título <alvo> do Sphinx, expondo os atributos self.alvo e self.título. Isto é útil para criar papéis de referência cruzada.

Diretivas¶

As diretivas são tratadas por classes derivadas de docutils.parsers.rst.Directive. Eles devem ser registrados por uma extensão usando Sphinx.add_directive() ou Sphinx.add_directive_to_domain().

class docutils.parsers.rst.Directive[código-fonte]¶

A sintaxe de marcação da nova diretiva é determinada pelos cinco atributos de classe a seguir:

required_arguments = 0¶: Número de argumentos de diretiva necessários.

optional_arguments = 0¶: Número de argumentos opcionais após os argumentos obrigatórios.

final_argument_whitespace = False¶: O argumento final pode conter espaços em branco?

option_spec = None¶

Mapeamento de nomes de opções para funções validadoras.

As funções validadoras de opções recebem um único parâmetro, o argumento da opção (ou None se não for fornecido), e devem validá-lo ou convertê-lo para o formato apropriado. Eles levantam ValueError ou TypeError para indicar falha.

Existem vários validadores predefinidos e possivelmente úteis no módulo docutils.parsers.rst.directives.

has_content = False¶: A diretiva pode ter conteúdo?

Novas diretivas devem implementar o método run():

run()[código-fonte]¶: Este método deve processar os argumentos, opções e conteúdo da diretiva e retornar uma lista de nós Docutils/Sphinx que serão inseridos na árvore do documento no ponto onde a diretiva foi encontrada.

Os atributos de instância que são sempre definidos na diretiva são:

name¶: O nome da diretiva (útil ao registrar a mesma classe de diretiva com vários nomes).

arguments¶: Os argumentos apresentados à diretiva, em forma de lista.

options¶: As opções dadas à diretiva, como uma opção de mapeamento de dicionário, nomeiam para valores validados/convertidos.

content¶: O conteúdo da diretiva, se fornecido, como ViewList.

lineno¶: O número absoluto da linha em que a diretiva apareceu. Este nem sempre é um valor útil; use srcline em vez disso.

content_offset¶: Deslocamento interno do conteúdo da diretiva. Usado ao chamar nested_parse (veja abaixo).

block_text¶: A string que contém toda a diretiva.

state¶
state_machine¶: O estado e a máquina de estado que controla a análise. Usado para nested_parse.

Ver também

HOWTO Creating directives da documentação do Docutils

Analisando o conteúdo da diretiva como reStructuredText¶

Muitas diretivas conterão mais marcações que devem ser analisadas. Para fazer isso, use uma das seguintes APIs do método run():

O primeiro método analisa todo o conteúdo da diretiva como marcação, enquanto o segundo analisa apenas a string text fornecida. Ambos os métodos retornam os nós Docutils analisados em uma lista.

Os métodos são usados como demonstrado a seguir.

def run(self) -> list[Node]:
    # either
    parsed = self.parse_content_to_nodes()
    # or
    parsed = self.parse_text_to_nodes('spam spam spam')
    return parsed

Nota

Os métodos utilitários acima foram adicionados no Sphinx 7.4. Antes do Sphinx 7.4, os seguintes métodos deviam ser usados para analisar o conteúdo:

self.state.nested_parse
sphinx.util.nodes.nested_parse_with_titles() essa isso permite títulos no conteúdo analisado.

def run(self) -> list[Node]:
    container = docutils.nodes.Element()
    # either
    nested_parse_with_titles(self.state, self.result, container, self.content_offset)
    # or
    self.state.nested_parse(self.result, self.content_offset, container)
    parsed = container.children
    return parsed

Para analisar a marcação em linha, use parse_inline(). Deve ser utilizado apenas para textos que sejam de uma única linha ou parágrafo e não contenham quaisquer elementos estruturais (títulos, transições, diretivas, etc.).

Nota

sphinx.util.docutils.switch_source_input() permite alterar o arquivo fonte (entrada) durante a análise do conteúdo de uma diretiva. É útil analisar conteúdo misto, como em sphinx.ext.autodoc, onde é usado para analisar docstrings.

from sphinx.util.docutils import switch_source_input
from sphinx.util.parsing import nested_parse_to_nodes

# Switch source_input between parsing content.
# Inside this context, all parsing errors and warnings are reported as
# happened in new source_input (in this case, ``self.result``).
with switch_source_input(self.state, self.result):
    parsed = nested_parse_to_nodes(self.state, self.result)

Descontinuado desde a versão 1.7: Até o Sphinx 1.6, sphinx.ext.autodoc.AutodocReporter era usado para este propósito. Ele foi substituído por switch_source_input().

ViewLists e StringLists¶

Docutils representa as linhas fonte do documento em uma classe StringList, que herda de ViewList, ambas no módulo docutils.statemachine. Esta é uma lista com funcionalidade estendida, incluindo que o fatiamento cria visualizações da lista original e que a lista contém informações sobre os números das linhas do código-fonte.

O atributo Directive.content é um StringList. Se você gerar conteúdo para ser analisado como reStructuredText, você terá que criar um StringList para as APIs do Docutils. As funções utilitárias fornecidas pelo Sphinx tratam disso automaticamente. Importantes para a geração de conteúdo são os seguintes pontos:

O construtor de ViewList recebe uma lista de strings (linhas) e um nome de origem (documento).
O método ViewList.append() leva uma linha e um nome de origem também.