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
类型:
bool
默认:
True

如果此项为 True，viewcode 扩展将发出 viewcode-follow-imported 事件，以由其他扩展解析模块名称。

版本 1.3 中添加。

版本 1.8 中更改: 从 viewcode_import 重命名为 viewcode_follow_imported_members。

viewcode_enable_epub
类型:
bool
默认:
False

如果此项为 True，即使您使用 epub 构建器，viewcode 扩展也会启用。此扩展会生成 toctree 之外的页面，但这不符合 epub 格式的要求。

直到 1.4.x 版本，此扩展始终启用。如果您想生成与 1.4.x 相同的 epub，您应该设置为 True，但这会降低 epub 格式检查器的评分。

版本 1.5 新增。

警告

并非所有 epub 阅读器都支持 viewcode 扩展生成的页面。这些阅读器会忽略指向不在 toctree 下的页面的链接。

某些阅读器的渲染结果会损坏，即使阅读器支持，epubcheck 的评分也会变差。

viewcode_line_numbers
类型:
bool
默认:
False

如果设置为 True，行号将内联添加到高亮代码中。

版本 7.2 中新增。

viewcode-find-source(app, modname)

版本 1.8 中新增。

查找模块的源代码。此事件的处理程序应返回源代码本身以及一个标签字典的元组。该字典将类、函数、属性等的名称映射到其类型、起始行号和结束行号的元组。类型应为“class”、“def”或“other”之一。

参数:

  • app – Sphinx 应用程序对象。

  • modname – 要查找源代码的模块名称。

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

版本 1.8 中新增。

查找属性的原始模块名称。

参数:

  • app – Sphinx 应用程序对象。

  • modname – 属性所属模块的名称。

  • attribute – 要跟踪的成员名称。