如何让Sphinx正确识别`:param`等文档标注元素？

出现该问题的核心原因是Sphinx的相关解析扩展未正确启用，或docstring格式、autodoc配置不符合要求，具体分为几种常见场景：

• 仅启用了基础功能，未正确配置sphinx.ext.autodoc的核心参数，导致函数/类的docstring内标注未被扫描解析
• 若使用Google、NumPy风格的docstring，未启用sphinx.ext.napoleon扩展，无法将非原生reST的参数标注转换为Sphinx可识别的格式
• docstring内的:param标注语法不符合规范，比如缩进错误、冒号格式错误，导致解析器忽略该部分内容
• 若使用Markdown编写docstring，未安装配置Markdown解析扩展，reST风格的标注无法被识别

按以下步骤逐一排查配置即可：

1. 检查项目根目录下的conf.py文件，确保扩展列表已添加必要扩展，示例配置如下：

extensions = [
    'sphinx.ext.autodoc',  # 必须启用，负责解析代码docstring
    'sphinx.ext.napoleon', # 若使用Google/NumPy风格docstring则必须加
    # 若用Markdown写docstring，额外加 'm2r2' 或 'sphinx_markdown_parser'
]

2. 在conf.py中添加autodoc默认配置，确保所有成员的docstring都被扫描：

autodoc_default_options = {
    'members': True,
    'undoc-members': True,
    'show-inheritance': True,
}

3. 检查代码中docstring的格式是否符合规范，示例正确写法如下：

def render(content: str, template: str) -> str:
    """渲染指定内容到模板

    :param content: 待渲染的原始内容
    :type content: str
    :param template: 渲染使用的模板字符串
    :type template: str
    :return: 渲染完成的结果字符串
    :rtype: str
    """
    # 业务逻辑

注意:param行需要和上方描述文本保持相同缩进层级，换行的描述内容需要比:param多缩进至少2个空格。
4. 若完成上述配置后仍有问题，升级Sphinx到最新版本后重新构建即可：
pip install -U sphinx
重新构建使用命令：. \make.bat html

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