Question

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

我在扩展程序中使用autodoc，napoleon和recommonmark。

如何在我的文档字符串中<< strong>使狮身人面像解析降价？

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扩展名recommonmark相同的Markdown解析器，并且与m2r一样快，这意味着与本地reStructuredText相比，构建时间几乎没有影响。

强制sphinx解释python docstrings中的markdown而不是重组文本

1 个答案: