pdoc文档生成工具参数解析格式问题解决方案

pdoc作为Python文档生成工具，在15.0.1版本中出现了一个影响NumPy风格文档字符串解析的问题。当用户使用NumPy风格的参数文档格式时，生成的HTML文档会将所有参数描述合并为单个连续字符串，而不是按照预期格式进行分段和加粗显示。

问题现象

典型的NumPy风格文档字符串示例如下：

def example_func(param1, param2):
    '''
    Parameters
    ----------
    param1 : int
        第一个参数的描述
    param2 : str, optional
        第二个参数的描述，可选参数
    '''

在正常情况下，pdoc应当将这种格式解析为：

• param1 : int
  第一个参数的描述
• param2 : str, optional
  第二个参数的描述，可选参数

但在问题版本中，输出会变成： Parameters param1 : int 第一个参数的描述 param2 : str, optional 第二个参数的描述，可选参数

问题原因

这个问题源于pdoc 15.0.1版本对文档字符串解析逻辑的调整。默认情况下，pdoc不再自动识别NumPy风格的文档格式，需要显式指定文档格式参数。

解决方案

要解决这个问题，有两种方法：

1. 使用命令行参数指定文档格式： 在生成文档时添加--docformat numpy参数：

   pdoc --math --docformat numpy -o html 模块名
   

2. 在代码中指定文档格式： 在模块的__init__.py文件中添加：

   __docformat__ = 'numpy'
   

最佳实践建议

1. 对于使用NumPy风格文档字符串的项目，建议在项目根目录的__init__.py中固定文档格式，避免依赖命令行参数。

2. 在编写文档字符串时，确保遵循标准的NumPy文档字符串格式：

   • 参数名称和类型说明在同一行
   • 参数描述从下一行开始，缩进4个空格
   • 使用明确的章节标题（Parameters, Returns等）

3. 对于可选参数，建议在类型说明后添加", optional"标记

兼容性说明

这个问题主要影响pdoc 15.x版本。如果项目需要兼容多个pdoc版本，可以考虑在文档生成脚本中检测pdoc版本并自动添加相应参数。

通过以上方法，可以确保NumPy风格的文档字符串在pdoc中正确解析和显示，生成专业、易读的API文档。