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

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. O padrão é True.

Adicionado na versão 1.3.

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

viewcode_enable_epub

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.

Até 1.4.x, essa extensão sempre estava habilitada. Caso desejar gerar epub como na 1.4.x, pode habilitar Verdadeiro, mas os verificadores formato epub serão degradados.

O padrão é False.

Adicionado na versão 1.5.

Aviso

Nem todas páginas de leitores epub são suportadas, através do código gerado por essa extensão. Esses leitores ignoram páginas que não estão sob toctree.

Alguns leitores renderizam resultados corrompidos e epubcheck rankeia pior mesmo quando suportados.

viewcode_line_numbers

Default: False.

If set to True, inline line numbers will be added to the highlighted code.

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 do aplicativo 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 do aplicativo Sphinx.

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

• attribute – O nome do membro a seguir.