如何让Sphinx解析Python文档字符串中的Markdown而非reStructuredText

我之前也碰到过一模一样的困扰——recommonmark确实只对手动编写的.md文件生效，没法处理代码里的文档字符串。不过有几个靠谱的方案能解决这个问题，下面一步步来：

方法一：使用m2r2扩展（推荐） #

m2r2是m2r的维护分支，专门用来在Sphinx中同时支持RST和Markdown，包括解析文档字符串里的Markdown语法。

步骤1：安装m2r2 #

在终端里运行：

pip install m2r2

步骤2：修改Sphinx的conf.py配置 #

更新扩展列表，把recommonmark替换成m2r2（或者保留recommonmark同时添加m2r2，不过更建议直接用m2r2），并配置支持的源文件后缀：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'm2r2'  # 替换recommonmark
]

# 同时支持.rst和.md文件
source_suffix = ['.rst', '.md']

步骤3：添加m2r2的额外配置 #

在conf.py末尾加上这个setup函数，确保文档字符串里的Markdown能被正确解析：

def setup(app):
    # 启用相对链接解析
    app.add_config_value('m2r2_parse_relative_links', True, 'env')
    # 允许匿名引用
    app.add_config_value('m2r2_anonymous_references', True, 'env')
    # 启用行内数学公式（如果不需要可以设为True）
    app.add_config_value('m2r2_disable_inline_math', False, 'env')

这样配置后，autodoc提取的文档字符串里的Markdown语法（比如加粗**text**、斜体*text*、代码块...、列表等）都会被Sphinx正确渲染。

方法二：自定义文档字符串处理（进阶） #

如果你不想换扩展，想继续用recommonmark，可以自定义一个处理函数，在autodoc提取文档字符串后用recommonmark的解析器转换。不过这个方法比较繁琐，示例如下：

步骤1：在conf.py中添加自定义处理函数 #

from recommonmark.parser import CommonMarkParser

def docstring_markdown(app, what, name, obj, options, lines):
    # 将文档字符串列表合并为字符串
    docstring = '\n'.join(lines)
    # 用recommonmark解析Markdown为RST
    parser = CommonMarkParser()
    rst = parser.parse(docstring)
    # 替换原文档字符串为解析后的RST
    lines.clear()
    lines.extend(rst.split('\n'))

def setup(app):
    # 连接autodoc的事件
    app.connect('autodoc-process-docstring', docstring_markdown)

不过这种方法可能会和napoleon的处理顺序冲突，需要调整事件优先级，不如m2r2省心。

测试示例 #

比如你有这样的Python函数：

def calculate_area(radius):
    """Calculate the area of a circle.

    **Formula**: Area = π * r²

    Args:
        radius (*float*): Radius of the circle (must be positive)

    Returns:
        *float*: Calculated area

    Example:
    ```python
    area = calculate_area(5)
    print(area)  # Output: ~78.54
    ```
    """
    import math
    return math.pi * radius **2

用m2r2配置后，生成的文档会正确渲染加粗的公式、代码块和参数说明。

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