Desenvolvendo extensões para Sphinx

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

Here are a few things you can do in an extension:

  • Add new builders to support new output formats or actions on the parsed documents.

  • Register custom reStructuredText roles and directives, extending the markup using the API Marcações Docutils.

  • Add custom code to so-called “hook points” at strategic places throughout the build process, allowing you to register a hook and run specialized code. For example, see the Sphinx core events.

An extension is simply a Python module with a setup() function. A user activates the extension by placing the extension’s module name (or a sub-module) in their extensions configuration value.

When sphinx-build is executed, Sphinx will attempt to import each module that is listed, and execute yourmodule.setup(app). This function is used to prepare the extension (e.g., by executing Python code), linking resources that Sphinx uses in the build process (like CSS or HTML files), and notifying Sphinx of everything the extension offers (such as directive or role definitions). The app argument is an instance of Sphinx and gives you control over most aspects of the Sphinx build.

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 em extensions

The rest of this page describes some high-level aspects of developing extensions and various parts of Sphinx’s behavior that you can control. For some examples of how extensions can be built and used to control different parts of Sphinx, see the Tutoriais de Extensão.

Objetos importantes

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

Applicação

O objeto de 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, o aplicativo estará disponível como env.app.

Ambiente

O objeto do ambiente de construção (geralmente chamado env) é uma instância de BuildEnvironment. Ele é responsável por analisar os documentos de origem, armazena todos os metadados sobre a coleção de documentos e é serializado em disco após cada compilaçã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 recriações incrementais.

Se você tiver o objeto do aplicativo 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 do aplicativo, o construtor estará disponível como app.builder.

Config

O objeto de 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 desses objetos, consulte Tutoriais de Extensão.

Fases 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.

Phase 0: Inicialização

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

Phase 1: Leitura

Na Fase 1, todos os arquivos de origem (e em compilações subsequentes, aqueles que são novos ou alterados) são lidos e analisados. Esta é a fase em que diretivas e funções são encontradas pelos docutils e o código correspondente é executado. A saída desta fase é um doctree para cada arquivo de origem; 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.

There are nodes provided by docutils, which are documented in the docutils documentation. Additional nodes are provided by Sphinx and documented here.

Durante a leitura, o ambiente de compilação é atualizado com todos os dados de meta e referência cruzada dos documentos lidos, como labels, 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 e consistências

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-4.

Para ver um exemplo de aplicação, consulte Developing a “TODO” extension.

Extensões Metadados

Novo 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 (ver needs_extensions) e finalidades de informação. Se não informado será apresentado "versão desconhecida"

  • 'env_version': um inteiro que identifica a versão da estrutura de dados env 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, ex. deve ser explicitado que sua função pode usar processamento paralelo, após a devida comprovação através dos testes.

    Nota

    The parallel-read-safe extension must satisfy the following conditions:

    • The core logic of the extension is parallely executable during the reading phase.

    • It has event handlers for env-merge-info and env-purge-doc events if it stores dataa to the build environment object (env) during the reading phase.

  • '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

    The parallel-write-safe extension must satisfy the following conditions:

    • The core logic of the extension is parallely executable during the writing phase.

APIs usadas para gravar extensões

These sections provide a more complete description of the tools at your disposal when developing Sphinx extensions. Some are core to Sphinx (such as the Application API) while others trigger specific behavior (such as the API i18n)