sphinx.ext.viewcode – Add links to highlighted source code

模块作者： Georg Brandl

1.0 新版功能.

This extension looks at your Python object descriptions (.. class::, .. function:: etc.) and tries to find the source files where the objects are contained. When found, a separate HTML page will be output for each module with a highlighted version of the source code, and a link will be added to all object descriptions that leads to the source code of the described object. A link back from the source to the description will also be inserted.

警告

Basically, viewcode extension will import the modules being linked to. If any modules have side effects on import, these will be executed when sphinx-build is run.

If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition.

In addition, if you don’t want to import the modules by viewcode, you can tell the location of the location of source code to viewcode using the viewcode-find-source event.

If viewcode_follow_imported_members is enabled, you will also need to resolve imported attributes using the viewcode-follow-imported event.

This extension works only on HTML related builders like html, applehelp, devhelp, htmlhelp, qthelp and so on except singlehtml. By default epub builder doesn’t support this extension (see viewcode_enable_epub).

Configuration

viewcode_follow_imported_members

If this is True, viewcode extension will emit viewcode-follow-imported event to resolve the name of the module by other extensions. The default is True.

1.3 新版功能.

在 1.8 版更改: Renamed from viewcode_import to viewcode_follow_imported_members.

viewcode_enable_epub

If this is True, viewcode extension is also enabled even if you use epub builders. This extension generates pages outside toctree, but this is not preferred as epub format.

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

The default is False.

1.5 新版功能.

警告

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

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

viewcode-find-source(app, modname)

1.8 新版功能.

Find the source code for a module. An event handler for this event should return a tuple of the source code itself and a dictionary of tags. The dictionary maps the name of a class, function, attribute, etc to a tuple of its type, the start line number, and the end line number. The type should be one of “class”, “def”, or “other”.

Parameters

  • app – The Sphinx application object.

  • modname – The name of the module to find source code for.

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

1.8 新版功能.

Find the name of the original module for an attribute.

Parameters

  • app – The Sphinx application object.

  • modname – The name of the module that the attribute belongs to.

  • attribute – The name of the member to follow.