API de retorno de chamada de eventos

Conectar funções de retorno de chamada a eventos é uma maneira simples de estender o Sphinx, conectando-se ao processo de construção em vários pontos.

Use Sphinx.connect() em uma função setup da extensão, ou uma função setup no conf.py do seu projeto, para conectar funções aos eventos:

def source_read_handler(app, docname, source):
    print('do something here...')

def setup(app):
    app.connect('source-read', source_read_handler)

Ver também

As extensões podem adicionar seus próprios eventos usando Sphinx.add_event() e chamando-os com EventManager.emit() ou EventManager.emit_firstresult().

Visão geral de eventos principais

Abaixo está uma visão geral do evento principal que acontece durante uma construção.

1. event.config-inited(app,config)
2. event.builder-inited(app)
3. event.env-get-outdated(app, env, added, changed, removed)
4. event.env-before-read-docs(app, env, docnames)

for docname in docnames:
   5. event.env-purge-doc(app, env, docname)

   if doc changed and not removed:
      6. source-read(app, docname, source)
      7. run source parsers: text -> docutils.document
         - parsers can be added with the app.add_source_parser() API
         - event.include-read(app, relative_path, parent_docname, content)
           is called for each include directive
      8. apply transforms based on priority: docutils.document -> docutils.document
         - event.doctree-read(app, doctree) is called in the middle of transforms,
           transforms come before/after this event depending on their priority.

9. event.env-merge-info(app, env, docnames, other)
   - if running in parallel mode, this event will be emitted for each process

10. event.env-updated(app, env)
11. event.env-get-updated(app, env)

if environment is written to disk:
   12. event.env-check-consistency(app, env)

13. event.write-started(app, builder)
    - This is called after ``app.parallel_ok`` has been set,
      which must not be altered by any event handler.

# The updated-docs list can be builder dependent, but generally includes all new/changed documents,
# plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
# For builders that output a single page, they are first joined into a single doctree before post-transforms
# or the doctree-resolved event is emitted
for docname in updated-docs:
   14. apply post-transforms (by priority): docutils.document -> docutils.document
   15. event.doctree-resolved(app, doctree, docname)
       - In the event that any reference nodes fail to resolve, the following may emit:
       - event.missing-reference(app, env, node, contnode)
       - event.warn-missing-reference(app, domain, node)

16. Generate output files
17. event.build-finished(app, exception)

Aqui está também um diagrama de fluxo dos eventos, dentro do contexto do processo de construção do Sphinx:

Fluxo de eventos principais do Sphinx

Detalhes de eventos principais

Aqui está uma lista mais detalhada desses eventos.

config-inited(app, config)

Parâmetros:

• app – Sphinx

• config – Config

Emitido quando o objeto de configuração foi inicializado.

Adicionado na versão 1.8.

builder-inited(app)

Parâmetros:

app – Sphinx

Emitido quando o objeto construtor foi criado (disponível como app.builder).

env-get-outdated(app, env, added, changed, removed)

Parâmetros:

• app – Sphinx

• env – BuildEnvironment

• added – Set[str]

• changed – Set[str]

• removed – Set[str]

retorna:

Sequence[str] de docnames adicionais para ler novamente

Emitido quando o ambiente determina quais arquivos fonte foram alterados e devem ser relidos. add, changed e removed são conjuntos de docnames determinados pelo ambiente. Você pode retornar uma lista de docnames para reler além destes.

Adicionado na versão 1.1.

env-purge-doc(app, env, docname)

Parâmetros:

• app – Sphinx

• env – BuildEnvironment

• docname – str

Emitido quando todos os rastros de um arquivo fonte devem ser limpos do ambiente, ou seja, se o arquivo fonte for removido ou antes de ser lido recentemente. Isto é para extensões que mantêm seus próprios caches em atributos do ambiente.

Por exemplo, existe um cache de todos os módulos no ambiente. Quando um arquivo fonte é alterado, as entradas do cache do arquivo são limpas, pois as declarações do módulo podem ter sido removidas do arquivo.

Adicionado na versão 0.5.

env-before-read-docs(app, env, docnames)

Parâmetros:

• app – Sphinx

• env – BuildEnvironment

• docnames – list[str]

Emitido após o ambiente ter determinado a lista de todos os arquivos adicionados e alterados e pouco antes de lê-los. Ele permite que os autores da extensão reordenem a lista de docnames (inplace) antes do processamento, ou adicionem mais docnames que o Sphinx não considerou alterados (mas nunca adicionem quaisquer docnames que não estejam em found_docs).

Você também pode remover nomes dos documentos; faça isso com cuidado, pois fará com que o Sphinx trate os arquivos alterados como inalterados.

Adicionado na versão 1.3.

source-read(app, docname, content)

Parâmetros:

• app – Sphinx

• docname – str

• content – list[str] com um único elemento, representando o conteúdo do arquivo fonte.

Emitido quando um arquivo fonte foi lido.

Você pode processar o content e substituir este item para implementar transformações no nível de fontes.

Por exemplo, se você quiser usar sinais $ para delimitar matemática em linha, como no LaTeX, você pode usar uma expressão regular para substituir $...$ por :math:`... `.

Adicionado na versão 0.5.

include-read(app, relative_path, parent_docname, content)

Parâmetros:

• app – Sphinx

• relative_path – Path representando o arquivo incluído relativo ao diretório fonte.

• parent_docname – str do nome do documento que contém a diretiva include.

• content – list[str] com um único elemento, representando o conteúdo do arquivo incluído.

Emitido quando um arquivo foi lido com a diretiva include.

Você pode processar o content e substituir este item para transformar o conteúdo incluído, como acontece com o evento source-read.

Adicionado na versão 7.2.5.

Ver também

A diretiva include e o evento source-read.

object-description-transform(app, domain, objtype, contentnode)

Parâmetros:

• app – Sphinx

• domain – str

• objtype – str

• contentnode – desc_content

Emitido quando uma diretiva de descrição de objeto é executada. Os argumentos domain e objtype são strings que indicam a descrição do objeto. E contentnode é um conteúdo para o objeto. Ele pode ser modificado no local.

Adicionado na versão 2.4.

doctree-read(app, doctree)

Parâmetros:

• app – Sphinx

• doctree – docutils.nodes.document

Emitido quando uma doctree foi analisada e lida pelo ambiente e está prestes a ser serializada com pickle. O doctree pode ser modificado no local.

missing-reference(app, env, node, contnode)

Parâmetros:

• app – Sphinx

• env – BuildEnvironment

• node – O nó pending_xref a ser resolvido. Seus atributos reftype, reftarget, modname e classname determinam o tipo e o alvo da referência.

• contnode – O nó que carrega o texto e a formatação dentro da referência futura e deve ser filho do nó de referência retornado.

retorna:

Um novo nó a ser inserido na árvore do documento no lugar do nó, ou None para permitir que outros manipuladores tentem.

Emitido quando uma referência cruzada a um objeto não pode ser resolvida. Se o manipulador de eventos puder resolver a referência, ele deverá retornar um novo nó docutils a ser inserido na árvore de documentos no lugar do nó node. Normalmente este nó é um nó reference contendo contnode como filho. Se o manipulador não puder resolver a referência cruzada, ele pode retornar None para permitir que outros manipuladores tentem ou aumentar NoUri para evitar que outros manipuladores tentem e suprimir um aviso sobre esta referência cruzada não foi resolvida.

Adicionado na versão 0.5.

warn-missing-reference(app, domain, node)

Parâmetros:

• app – Sphinx

• domain – O Domain da referência ausente.

• node – O nó pending_xref que não pôde ser resolvido.

retorna:

True se um aviso foi emitido, caso contrário None

Emitido quando uma referência cruzada a um objeto não pode ser resolvida mesmo após missing-reference. Se o manipulador de eventos puder emitir avisos para a referência ausente, ele deverá retornar True. As variáveis ​​de configuração nitpick_ignore e nitpick_ignore_regex evitam que o evento seja emitido para os nós correspondentes.

Adicionado na versão 3.4.

doctree-resolved(app, doctree, docname)

Parâmetros:

• app – Sphinx

• doctree – docutils.nodes.document

• docname – str

Emitido quando uma doctree foi “resolvida” pelo ambiente, ou seja, todas as referências foram resolvidas e os TOCs foram inseridos. A doctree pode ser modificada no local.

Este é o lugar para substituir nós personalizados que não possuem métodos de visitante nos escritores, para que não causem erros quando os escritores os encontrarem.

env-merge-info(app, env, docnames, other)

Parâmetros:

• app – Sphinx

• env – BuildEnvironment

• docnames – list[str]

• other – BuildEnvironment

Este evento só é emitido quando a leitura paralela de documentos está habilitada. É emitido uma vez para cada subprocesso que leu algum documento.

Você deve manipular esse evento em uma extensão que armazene dados no ambiente em um local customizado. Caso contrário, o ambiente do processo principal não terá conhecimento das informações armazenadas no subprocesso.

other é o objeto de ambiente do subprocesso, env é o ambiente do processo principal. docnames é um conjunto de nomes dos documentos que foram lidos no subprocesso.

Adicionado na versão 1.3.

env-updated(app, env)

Parâmetros:

• app – Sphinx

• env – BuildEnvironment

retorna:

iterável de str

Emitido após a leitura de todos os documentos, quando o ambiente e todas as doctrees estão atualizados.

Você pode retornar um iterável de docnames do manipulador. Estes documentos serão então considerados atualizados e serão (re)escritos durante a fase de redação.

Adicionado na versão 0.5.

Alterado na versão 1.3: O valor de retorno dos manipuladores agora é usado.

env-get-updated(app, env)

Parâmetros:

• app – Sphinx

• env – BuildEnvironment

retorna:

iterável de str

Emitido quando o ambiente determina quais arquivos fonte foram alterados e devem ser relidos. Você pode retornar um iterável de docnames para reler.

env-check-consistency(app, env)

Parâmetros:

• app – Sphinx

• env – BuildEnvironment

Emitido durante a fase de verificação de consistência. Você pode verificar a consistência dos metadados de todos os documentos.

Adicionado na versão 1.6.

write-started(app, builder)

Parâmetros:

• app – Sphinx

• builder – Builder

Emitido antes do construtor começar a resolver e escrever documentos.

Adicionado na versão 7.4.

build-finished(app, exception)

Parâmetros:

• app – Sphinx

• exception – Exception ou None

Emitido quando uma construção é concluída, antes da saída do Sphinx, geralmente usado para limpeza. Este evento é emitido mesmo quando o processo de construção levanta uma exceção, fornecida como argumento exception. A exceção é levantada novamente na aplicação após a execução dos manipuladores de eventos. Se o processo de construção não levantou nenhuma exceção, exception será None. Isto permite personalizar ações de limpeza dependendo do status da exceção.

Adicionado na versão 0.5.

Eventos específicos do construtor

Esses eventos são emitidos por construtores específicos.

html-collect-pages(app)

Parâmetros:

app – Sphinx

retorna:

iterável de (pagename, context, templatename) onde pagename e templatename são strings e context é um dict[str, Any].

Emitido quando o construtor HTML está começando a escrever páginas que não são de documento.

Você pode adicionar páginas para escrever retornando um iterável deste evento.

Adicionado na versão 1.0.

html-page-context(app, pagename, templatename, context, doctree)

Parâmetros:

• app – Sphinx

• pagename – str

• templatename – str

• context – dict[str, Any]

• doctree – docutils.nodes.document ou None

retorna:

str ou None

Emitido quando o construtor HTML cria um dicionário de contexto para renderizar um modelo – isso pode ser usado para adicionar elementos personalizadosao contexto.

O argumento pagename é o nome canônico da página que está sendo renderizada, ou seja, sem o sufixo .html e usando barras como separadores de caminho. O templatename é o nome do modelo a ser renderizado, será 'page.html' para todas as páginas dos documentos reStructuredText.

O argumento context é um dicionário de valores que são fornecidos ao mecanismo de modelo para renderizar a página e pode ser modificado para incluir valores personalizados.

O argumento doctree será uma doctree quando a página for criada a partir de documentos reStructuredText; será None quando a página for criada apenas a partir de um modelo HTML.

Você pode retornar uma string do manipulador, ele substituirá 'page.html' como o modelo HTML para esta página.

Dica

Você pode instalar arquivos JS/CSS para a página específica via Sphinx.add_js_file() e Sphinx.add_css_file() (desde v3.5.0).

Adicionado na versão 0.4.

Alterado na versão 1.3: O valor de retorno agora pode especificar um nome de modelo.

linkcheck-process-uri(app, uri)

Parâmetros:

• app – Sphinx

• uri – str do URI coletado

retorna:

str ou None

Emitido quando o construtor linkcheck coleta hiperlinks do documento.

Os manipuladores de eventos podem modificar o URI retornando uma string.

Adicionado na versão 4.1.

Previous

API de aplicação

Next

API de projeto