API do Sphinx para extensões¶
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 Marcações 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 Sphinx core events.
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 da extensão (ou um submódulo) em seu valor de configuração extensions.
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 deSphinx. 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 deBuildEnvironment. 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 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 recriações incrementais.
Se você tiver o objeto do aplicativo ou construtor, o ambiente estará disponível como
app.envoubuilder.env.- Construtor
O objeto construtor (geralmente chamado
builder) é uma instância de uma subclasse específica deBuilder. 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 emconf.pycomo atributos. É uma instância deConfig.A configuração está disponível como
app.configouenv.config.
Para ver um exemplo de uso desses objetos, consulte Tutoriais de extensão.
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.
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 construçã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 construçõ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 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.
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 construçã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.
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 (verneeds_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 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, 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 parallelly executable during the reading phase.
It has event handlers for
env-merge-infoandenv-purge-docevents if it stores data 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 parallelly executable during the writing phase.
APIs usadas para escrever 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)