如何让Jupyter Notebook正确渲染包含Sphinx标记的文档字符串

方案1：自定义渲染函数手动调用 #

你可以基于docutils编写一个简单的转换函数，手动调用即可看到格式化后的文档：

1. 确保已经安装docutils依赖
2. 在Notebook中运行如下代码定义转换工具：

from docutils.core import publish_string
from IPython.display import HTML, display

def render_doc(obj):
    if not obj.__doc__:
        print("无可用文档")
        return
    # 处理Sphinx标记的rst转HTML
    html = publish_string(
        obj.__doc__,
        writer_name="html",
        settings_overrides={"output_encoding": "unicode", "halt_level": 5}
    )
    display(HTML(html))

3. 需要查看文档时，直接调用render_doc(Foo.bar)即可，支持:py:meth:、:py:class:等常用Sphinx标记的正确渲染，比原始rst可读性高很多。
   如果你的文档字符串用到了Sphinx自定义扩展的特殊标记，在publish_string的settings_overrides参数中添加对应扩展的适配配置即可兼容。

方案2：修改IPython默认逻辑，实现?查询自动渲染 #

如果不想每次手动调用自定义函数，可以修改IPython的启动配置，让默认的?查询自动完成渲染：

• 找到你的IPython启动配置目录，默认路径为~/.ipython/profile_default/startup/
• 在该目录下新建任意.py后缀的启动文件，比如doc_render.py，将上述render_doc函数的代码写入，同时注册为IPython的文档渲染钩子
• 重启Jupyter内核后，所有使用?查询的文档字符串都会自动按Sphinx规则渲染输出，无需额外操作。

方案3：使用预构建的Jupyter扩展 #

你也可以直接安装支持Sphinx格式文档字符串渲染的Jupyter扩展，这类扩展通常同时兼容Google、NumPy等多种文档字符串格式，安装启用后不需要手动写代码配置，默认即可实现格式化渲染。

内容的提问来源于stack exchange，提问作者Batman