pdoc3 Args渲染异常求助：M2 Mac环境下格式错误

环境差异 #

• 迁移前（正常环境）：M1 Mac，系统Ventura 13.6，Python 3.9.16（pyenv管理），pdoc 0.10.0
• 迁移后（异常环境）：M2 Mac，系统Ventura 13.6.2，相同Python版本与pdoc版本

示例源码 #

"""
  Args:  
      script_path (str, optional): the full s3 or github uri, or local path to the script you want the service to execute. Defaults to "./script.py".  
"""

正确渲染的HTML结果 #

<h2 id="args">Args</h2> 
<dl>
<dt><strong><code>script_path</code></strong> :&ensp;<code>str</code>, optional</dt>
<dd>the full s3 or github uri, or local path to the script you want the service to execute. Defaults to "./script.py".</dd>
</dl>

当前错误渲染的HTML结果 #

<p>Args:<br>
script_path (str, optional): the full s3 or github uri, or local path
to the script you want the service to execute. Defaults to "./script.py".
</p>

排查方向 #

• 核对依赖版本一致性：在两台机器上执行pip freeze | grep -E 'pdoc|markdown|docutils'，确保所有相关依赖版本完全一致。M2环境可能因系统差异自动安装了不同版本的markdown/docutils等解析库，导致pdoc的文档解析逻辑异常。
• 验证文档字符串格式：确认当前代码的文档字符串缩进、换行与M1环境完全一致，尤其是Args:行的缩进和参数行的缩进是否严格匹配。pdoc对reStructuredText格式的文档字符串敏感度极高，细微的格式差异会导致解析失败。
• 清理缓存重新测试：删除pdoc生成的本地缓存目录（通常为.pdoc），重新执行pdoc命令生成文档，避免缓存残留导致的异常。
• 测试最小化用例：创建仅包含上述示例Args段的极简Python脚本，单独用pdoc渲染，排查是否是项目中其他文档字符串的格式问题干扰了整体解析。

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