强制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不提供开箱即用的功能。它应该是一个容易添加的功能。就个人而言，我m2r用于项目的转换。因为它很快-比例如快得多pandoc。速度很重要，因为转换是即时进行的，并分别处理每个文档字符串。除此之外，任何Markdown-to-reST转换器都可以。

安装m2r以下内容并将其添加到Sphinx的配置文件中conf.py：

import m2r

def docstring(app, what, name, obj, options, lines):
    md  = '\n'.join(lines)
    rst = m2r.convert(md)
    lines.clear()
    for line in rst.splitlines():
        lines.append(line)

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

[ 编辑添加... ]

就像上面一样，但是commonmark：

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()
    for line in rst.splitlines():
        lines.append(line)

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

它使用与Sphinx扩展名相同的Markdown解析器，recommonmark并且速度与一样快m2r，这意味着与本地reStructuredText相比，构建时间几乎没有影响。