sphinx.ext.viewcode -- 添加到高亮源代码的链接

Module author: Georg Brandl

Added in version 1.0.

此插件查看您的 Python 对象描述(.. class::.. function:: 等)并尝试查找包含对象的源文件。找到后,将为每个模块输出单独的 HTML 页面,其中包含源代码的高亮版本,并将添加到所有对象描述的链接,该链接指向所描述对象的源代码。还将插入从源到描述的链接。

Warning

基本上,viewcode 插件将导入链接到的模块。如果任何模块在导入时具有副作用,这些副作用将在运行 sphinx-build 时执行。

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

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

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

此插件仅适用于 HTML 相关构建器,如 htmlapplehelpdevhelphtmlhelpqthelp 等,但不适用于 singlehtml。"默认情况下,epub 构建器不支持此插件(请参见 viewcode_enable_epub)。

配置

viewcode_follow_imported_members

如果为 True,viewcode 插件将发出 viewcode-follow-imported 事件以通过其他插件解析模块的名称。默认为 True

Added in version 1.3.

Changed in version 1.8: 重命名 viewcode_importviewcode_follow_imported_members

viewcode_enable_epub

如果为 True,即使使用 epub 构建器,viewcode 插件也将启用。此插件在 toctree 之外生成页面,但这不是 epub 格式的首选。

在 1.4.x 之前,此插件始终启用。如果要生成与 1.4.x 相同的 epub,应将其设置为 True,但 epub 格式检查器的分数会变差。

默认为 False

Added in version 1.5.

Warning

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

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

viewcode_line_numbers

默认为 False

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

Added in version 7.2.

viewcode-find-source(app, modname)

Added in version 1.8.

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

参数:
  • app -- Sphinx 应用程序对象。

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

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

Added in version 1.8.

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

参数:
  • app -- Sphinx 应用程序对象。

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

  • attribute -- 要跟随的成员的名称。