sphinx.ext.viewcode – Adiciona links ao código destacado

Autor do módulo: Georg Brandl

Adicionado na versão 1.0.

Essa extensão exibe nas descrições do Objeto Python (.. class::, .. function:: etc.) e tenta encontrar o arquivo fonte onde o objeto está contido. Quando encontrado, uma página separada HTML é criada para cada módulo com versão destacada no código fonte, e um link será adicionado em todas as descrições que levam ao código fonte do objeto descrito. Um link de retorno do fonte para a descrição também é inserido.

Aviso

Basicamente, a extensão viewcode importará os módulos que estão sendo vinculados. Se algum módulo tiver efeitos colaterais na importação, eles serão executados quando o sphinx-build for executado.

Se os scripts do seu documento, (diferentemente de módulos de biblioteca), certificar-se que suas rotinas main estejam protegidas por um if __name__ == '__main__' condição.

Além disso, se você não quiser importar os módulos por viewcode, poderá informar a localização do local do código-fonte para viewcode usando o evento viewcode-find-source.

Se viewcode_follow_imported_members estiver ativada, você também precisará resolver os atributos importados usando o evento viewcode-follow-imported.

A extensão funciona somente com construtores HTML e construtores como html, applehelp, devhelp, htmlhelp, qthelp e assim por diante, exceto singlehtml. Através do padrão epub montador não suporta essa extensão (ver viewcode_enable_epub).

Configuração

viewcode_follow_imported_members
Type:
bool
Default:
True

Se isso for True, a extensão viewcode emitirá um evento viewcode-follow-imported para resolver o nome do módulo por outras extensões.

Adicionado na versão 1.3.

Alterado na versão 1.8: Renomeado de viewcode_import para viewcode_follow_imported_members.

viewcode_enable_epub
Type:
bool
Default:
False

Se esse valor for Verdadeiro, a extensão viewcode estará habilitada para usar com construtores epub. Essa extensão gera páginas fora de toctree, mas não é o formato preferencial do epub.

Until 1.4.x, this extension is always enabled. If you want to generate epub as same as 1.4.x, you should set this to True, but epub format checker’s score worsens.

Adicionado na versão 1.5.

Aviso

Not all epub readers support pages generated by viewcode extension. These readers ignore links to pages that are not under any toctree.

Some reader’s rendering result are corrupted and epubcheck’s score becomes worse even if the reader supports these pages.

viewcode_line_numbers
Type:
bool
Default:
False

Se definido como True, os números das linhas embutidas serão adicionados ao código realçado.

Adicionado na versão 7.2.

viewcode-find-source(app, modname)

Adicionado na versão 1.8.

Encontre o código fonte para um módulo. Um manipulador de eventos para este evento deve retornar uma tupla do próprio código-fonte e um dicionário de tags. O dicionário mapeia o nome de uma classe, função, atributo, etc, para uma tupla de seu tipo, o número da linha inicial e o número da linha final. O tipo deve ser class, def ou other.

Parâmetros:

  • app – O objeto de aplicação do Sphinx.

  • modname – O nome do módulo para encontrar o código fonte para.

viewcode-follow-imported(app, modname, attribute)

Adicionado na versão 1.8.

Encontre o nome do módulo original para um atributo.

Parâmetros:

  • app – O objeto de aplicação do Sphinx.

  • modname – O nome do módulo ao qual o atributo pertence.

  • attribute – O nome do membro a seguir.