如何用Sphinx为param.Parameterized子类生成文档？

核心问题解决思路 #

针对Sphinx autodoc无法提取param参数文档的问题，目前有几种成熟的解决方案，从简单到进阶如下：

1. 专用Sphinx扩展：sphinx-paramlinks #

这是社区专门为解决该问题开发的扩展，能让autodoc自动识别并渲染param.Parameterized子类的参数文档字符串，效果和Jupyter中A?显示的一致。

操作步骤： #

• 安装扩展：

  pip install sphinx-paramlinks
  

• 在Sphinx配置文件conf.py中添加该扩展：

  extensions = [
      # 保留你已有的其他扩展（比如sphinx.ext.autodoc）
      'sphinx_paramlinks'
  ]
  

• 正常使用autodoc指令即可，比如：

  .. autoclass:: your_package.module.A
     :members:
  

  生成的文档会自动包含类A中所有param参数的说明，无需额外配置。

2. 手动适配autodoc（无依赖方案） #

如果不想引入新扩展，可以通过自定义autodoc的成员过滤逻辑来实现：

• 在conf.py中加入以下代码：

  from param import Parameterized
  
  def autodoc_include_param_attributes(app, what, name, obj, skip, options):
      # 让autodoc不跳过param生成的属性
      if isinstance(obj, Parameterized) and name in obj.param:
          return False
      return skip
  
  def setup(app):
      app.connect('autodoc-skip-member', autodoc_include_param_attributes)
  

• 之后可以用autodata指令单独提取参数文档，或者在类文档中手动关联：

  .. autoclass:: your_package.module.A
  .. autodata:: your_package.module.A.param.your_param_name
  

  这种方式需要手动维护部分参数的文档引用，但无需额外安装包。

3. Holoviz生态工具：nbsite进阶方案 #

如果你的项目基于Holoviz（param是该生态的核心组件之一），可以用nbsite直接生成完整的文档站点，它对param类的文档支持是内置的：

• 安装nbsite：

  pip install nbsite
  

• 初始化项目并配置后，执行：

  nbsite build
  

  生成的站点会自动处理所有param参数的文档，还支持交互式预览等功能。

总结 #

最省心的方案是使用sphinx-paramlinks扩展，它能无缝对接Sphinx autodoc，自动提取param参数的文档字符串，几乎不需要额外配置。

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