python - 强制 Sphinx 在 Python 文档字符串中解释 Markdown 而不是 reStructuredText

Question

我正在使用 Sphinx 来记录一个 python 项目。我想在我的文档字符串中使用 Markdown 来格式化它们。 即使我使用 recommonmark扩展名，它仅涵盖 .md手动编写的文件，而不是文档字符串。

我用 autodoc , napoleon和 recommonmark在我的扩展中。

如何使 sphinx 解析 Markdown 在我的文档字符串中？

Answer 1

Sphinx 的 Autodoc 扩展发出一个名为 autodoc-process-docstring 的事件每次它处理一个文档字符串。我们可以使用该机制将语法从 Markdown 转换为 reStructuredText。
不幸的是，Recommonmark不公开 Markdown-to-reST 转换器。它将解析后的 Markdown 直接映射到 Docutils对象，即与 Sphinx 相同的表示本身从 reStructuredText 内部创建。
相反，我使用 Commonmark用于我的项目中的转换。因为它很快——比 Pandoc 快得多， 例如。速度很重要，因为转换是即时进行的，并单独处理每个文档字符串。除此之外，任何 Markdown-to-reST 转换器都可以。 M2R2将是第三个例子。其中任何一个的缺点是它们不支持 Recommonmark 的语法扩展，例如对文档其他部分的交叉引用。只是基本的 Markdown 。
要插入 Commonmark 文档字符串转换器，请确保已安装该软件包(pip install commonmark)并将以下内容添加到 Sphinx 的配置文件 conf.py :

import commonmark

def docstring(app, what, name, obj, options, lines):
    md  = '\n'.join(lines)
    ast = commonmark.Parser().parse(md)
    rst = commonmark.ReStructuredTextRenderer().render(ast)
    lines.clear()
    lines += rst.splitlines()

def setup(app):
    app.connect('autodoc-process-docstring', docstring)

同时，Recommonmark 为 deprecated 2021 年 5 月。Sphinx 扩展 MyST ，一个功能更丰富的 Markdown 解析器，是推荐的替代品 by Sphinx和 by Read-the-Docs . MyST does not yet support文档字符串中的 Markdown 也是如此，但与上面相同的钩子(Hook)可用于通过 Commonmark 获得有限的支持。
此处概述的方法的一种可能替代方法是使用 MkDocs与 MkDocStrings插件，它将完全从流程中消除 Sphinx 和 reStructuredText。