API do Sphinx

Como muitos projetos necessitam de funcionalidades especiais em sua documentação, Sphix foi desenhado para ser extensível em diversos níveis.

Aqui estão algumas coisas que você pode fazer em uma extensão:

  • Adiciona um novo construtor para ter suporte aos novos formatos de saída ou ações nos documentos analisados.

  • Registra papéis e diretivas reStructuredText personalizadas, estendendo a marcação usando a API de marcações do Docutils.

  • Adiciona código personalizado aos chamados “pontos de gancho” em locais estratégicos ao longo do processo de construção, permitindo que você registre um gancho e execute código especializado. Por exemplo, veja API de retorno de chamada de eventos.

Uma extensão é simplesmente um módulo Python com uma função setup(). Um usuário ativa a extensão colocando o nome do módulo (ou submódulo) da extensão em seu valor de configuração extensions.

Quando sphinx-build é executado, o Sphinx tentará importar cada módulo listado e executar seumódulo.setup(app). Esta função é usada para preparar a extensão (por exemplo, executando código Python), vinculando recursos que o Sphinx usa no processo de construção (como arquivos CSS ou HTML) e notificando o Sphinx sobre tudo o que a extensão oferece (como definições de papéis ou diretivas). O argumento app é uma instância de Sphinx e dá a você controle sobre a maioria dos aspectos da construção do Sphinx.

Nota

A configuração do próprio arquivo pode ser tratada como uma extensão se ela contiver uma função setup(). Todas as outras extensões para serem carregadas devem estar listadas no valor de configuração extensions.

O restante desta página descreve alguns aspectos de alto nível do desenvolvimento de extensões e várias partes do comportamento do Sphinx que você pode controlar. Para alguns exemplos de como extensões podem ser construídas e usadas para controlar diferentes partes do Sphinx, veja o Tutoriais.

Objetos importantes

Existem vários objetos-chave cuja API você usará ao escrever uma extensão. São eles:

Applicação

O objeto aplicação (geralmente chamado app) é uma instância de Sphinx. Ele controla a maioria das funcionalidades de alto nível, como a configuração de extensões, o despacho de eventos e a produção de saída (logging).

Se você tiver o objeto de ambiente, a aplicação estará disponível como env.app.

Ambiente

O objeto ambiente de construção (geralmente chamado env) é uma instância de BuildEnvironment. Ele é responsável por analisar os documentos fonte, armazena todos os metadados sobre a coleção de documentos e é serializado em disco após cada construção.

Sua API fornece métodos para acessar metadados, resolver referências, etc. Também pode ser usada por extensões para armazenar em cache informações que devem persistir para reconstruções incrementais.

Se você tiver o objeto aplicação ou construtor, o ambiente estará disponível como app.env ou builder.env.

Construtor

O objeto construtor (geralmente chamado builder) é uma instância de uma subclasse específica de Builder. Cada classe de construtor sabe como converter os documentos analisados em um formato de saída ou processá-los (por exemplo, verificar links externos).

Se você tiver o objeto aplicação, o construtor estará disponível como app.builder.

Config

O objeto configuração (geralmente chamado config) fornece os valores dos valores de configuração definidos em conf.py como atributos. É uma instância de Config.

A configuração está disponível como app.config ou env.config.

Para ver um exemplo de uso destes objetos, consulte os tutoriais.

Fases da construção

Uma coisa que é vital para entender os mecanismos de extensão é a maneira como um projeto Sphinx é construído: isso funciona em várias fases.

digraph phases { graph [ rankdir = LR ] node [ shape = rect; style = filled; fillcolor ="#f7f7f7"; fontcolor = "#0a507a" ] Initialization -> Reading; Reading -> "Consistency checks"; "Consistency checks" -> Resolving; Resolving -> Writing; }

Fases da construção

Phase 0: Inicialização

Nesta fase, quase nada de interessante para nós acontece. O diretório fonte é pesquisado por arquivos fonte e as extensões são inicializadas. Se existir um ambiente de construção armazenado, ele será carregado, caso contrário, um novo será criado.

Phase 1: Leitura

Na Fase 1, todos os arquivos fonte (e em construções subsequentes, aqueles que são novos ou alterados) são lidos e analisados. Esta é a fase em que diretivas e papéis são encontradas pelos docutils e o código correspondente é executado. A saída desta fase é um doctree para cada arquivo fonte; isso é uma árvore de nós docutils. Para elementos de documento que não são totalmente conhecidos até que todos os arquivos existentes sejam lidos, nós temporários são criados.

Existem nós fornecidos por docutils, que são documentados na documentação do docutils. Nós adicionais são fornecidos pelo Sphinx e documentados aqui.

Durante a leitura, o ambiente de construção é atualizado com todos os dados de meta e referência cruzada dos documentos lidos, como rótulos, os nomes dos títulos, objetos descritos do Python e entradas de índice. Isso será usado posteriormente para substituir os nós temporários.

Os doctrees analisados são armazenados no disco porque não é possível manter todos eles na memória.

Phase 2: Verificações de consistência

Alguma verificação é feita para garantir que não haja surpresas nos documentos construídos.

Fase 3: Resolução

Agora que os metadados e os dados de referência cruzada de todos os documentos existentes são conhecidos, todos os nós temporários são substituídos por nós que podem ser convertidos em saída usando componentes chamados de transformações. Por exemplo, links são criados para referências de objetos existentes e nós literais simples são criados para aqueles que não existem.

Fase 4: Gravação

Esta fase converte os doctrees resolvidos no formato de saída desejado, como HTML ou LaTeX. Isso acontece por meio de um escritor chamado docutils, que visita os nós individuais de cada doctree e produz alguma saída no processo.

Nota

Alguns construtores se desviam desse plano de construção geral, por exemplo, o construtor que verifica links externos não precisa de nada além dos doctrees analisados e, portanto, não possui as fases 2 a 4.

Para ver um exemplo de aplicação, consulte Estendendo o processo de construção.

Metadados das extensões

Adicionado na versão 1.3.

A função setup() pode retornar um dicionário. Isso é tratado pelo Sphinx como extensão de metadados. Chaves dos metadados normalmente reconhecidas são:

  • 'version': uma palavra que identifica a versão da extensão. É utilizada para a verificação da versão mínima requerida (veja needs_extensions) e finalidades de informação. Se não informado será apresentado "unknown version".

  • 'env_version': um inteiro que identifica a versão da estrutura de dados do ambiente se a extensão armazena dados no ambiente. Ele é usado para detectar que a estrutura de dados foi alterada da última construção. As extensões precisam incrementar a versão quando a estrutura de dados for alterada. Se não for fornecido, o Sphinx considera que a extensão não armazena dados no ambiente.

  • 'parallel_read_safe': valor booleano que especifica se leitura paralela dos arquivos fontes pode ser usada, quando a extensão for carregada. O valor padrão é False, por exemplo, deve ser explicitado que sua função pode usar processamento paralelo, após a devida comprovação através dos testes.

    Nota

    A extensão parallel-read-safe deve satisfazer as seguintes condições:

    • A lógica central da extensão é executável paralelamente durante a fase de leitura.

    • Possui manipuladores de eventos para eventos env-merge-info e env-purge-doc se armazenar dados no objeto ambiente de construção (env) durante a fase de leitura.

  • 'parallel_write_safe': valor booleano que especifica que a gravação dos arquivos de saída pode ser usada quando sua extensão for carregada. Normalmente extensões não influenciam negativamente o processo, o valor padrão é True.

    Nota

    A extensão parallel-write-safe deve satisfazer as seguintes condições:

    • A lógica central da extensão é executável paralelamente durante a fase de gravação.

APIs usadas para escrever extensões

Estas seções fornecem uma descrição mais completa das ferramentas à sua disposição ao desenvolver extensões Sphinx. Alguns são essenciais para o Sphinx (como o API de aplicação) enquanto outros desencadeiam comportamentos específicos (como o API i18n)