如何让doctest兼容mkdocs中Markdown代码块内的示例？

以下是几个无需手动添加空行、同时满足文档美观渲染和测试通过的最优方案：

方案1：使用reStructuredText代码块格式（推荐） #

采用Python原生支持的reStructuredText代码块语法，mkdocstring会正常渲染为美观的代码块，doctest也能自动识别并跳过代码块指令，只执行测试代码：

"""
递归扁平化嵌套可迭代对象（包括字符串！），按从左到右的顺序返回所有元素。

示例：
--------
.. code-block:: python

    >>> [x for x in flatten([1,2,[3,4,[5],6],7,[8,9]])]
    [1, 2, 3, 4, 5, 6, 7, 8, 9]
"""

• 无需额外配置，两边需求完美兼容，没有多余空行或注释。

方案2：为Markdown代码块添加跳过注释 #

如果偏好Markdown风格代码块，可在代码块的首尾反引号行添加# doctest: +SKIP，让doctest跳过这些行，不影响mkdocstring渲染：

"""
递归扁平化嵌套可迭代对象（包括字符串！），按从左到右的顺序返回所有元素。

示例：
--------
```python # doctest: +SKIP
>>> [x for x in flatten([1,2,[3,4,[5],6],7,[8,9]])]
[1, 2, 3, 4, 5, 6, 7, 8, 9]
``` # doctest: +SKIP
"""

• 保持Markdown书写习惯，仅需两行注释即可兼容。

方案3：全局配置pytest忽略非测试行 #

通过pytest配置文件一次性处理所有文档字符串，无需修改代码：

在pytest.ini中添加：

[pytest]
doctest_ignore_lines = ^```, ^```$

该配置会让doctest忽略所有以```开头或结尾的行，避免将代码块标记误判为测试输出。

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