sphinx.ext.viewcode – 添加突出显示的源代码的链接

模块作者：Georg Brandl

1.0 新版功能.

这个扩展名查看你的Python对象描述(.. class::, .. function:: 等)并尝试查找包含对象的源文件。找到后，将为每个模块输出一个单独的HTML页面，其中包含源代码的突出显示版本，并且链接将添加到所有对象描述中，这些描述将导致所描述对象的源代码。还将插入从源到描述的链接。

警告

基本上， viewcode 扩展名将导入链接到的模块。如果任何模块在导入时有副作用，那么当运行 sphinx-build 时会执行这些副作用。

如果您记录脚本（而不是库模块），请确保它们的主例程受 if __name__ == '__main__' 条件的保护。

另外，如果你不想通过 viewcode 导入模块，你可以使用 viewcode-find-source 事件来告诉源代码 viewcode 的位置。 。

如果 viewcode_follow_imported_members 已启用，您还需要使用 viewcode-follow-imported 事件来解析导入的属性。

此扩展仅适用于HTML相关的构建器，如 html ， applehelp ， devhelp ， htmlhelp ， qthelp 等除了 singlehtml 。默认情况下， epub 构建器不支持此扩展（请参阅 viewcode_enable_epub）。

配置

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”.

参数

  • 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.

参数

  • app – The Sphinx application object.

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

  • attribute – The name of the member to follow.