sphinx.ext.viewcode – 添加链接到高亮的源代码¶
模块作者： Georg Brandl
Added in version 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¶
如果这是
True,viewcode 扩展将发出viewcode-follow-imported事件,以便通过其他扩展解析模块的名称.默认值是True.Added in version 1.3.
在 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.
警告
并非所有的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 – 要关注的成员名称.