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 相关构建器,如 html
、applehelp
、devhelp
、htmlhelp
、qthelp
等,但不适用于 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_import
为viewcode_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 -- 要跟随的成员的名称。