restructuredText 文档字符串到 .md 文件 [重复]答案

【问题标题】：restructuredText docstrings to .md files [duplicate]restructuredText 文档字符串到 .md 文件 [重复]
【发布时间】：2021-04-12 23:44:28
【问题描述】：

我有一个 Python 项目，我在其中使用 restructuredText 来评论/记录我的每个类/函数。这是我的文档字符串的示例：

"""
Updates the contacts birth date in batch
:param nb_contacts: nb_contacts: number of contacts to update
:param batch_size: size of the batch
:param context: airflow context
:return: true if update is successful
"""

我想从我的代码中生成 .md 文件。有什么办法吗？

【问题讨论】：

预期输出是什么？
只是寻找可以很好地显示在 git 上的东西和人类可读的 .md doc 文件。与 sphinx 生成的 .html 文档具有相同结构但在 .md 文件中的文档
请注意，cmets 和 docstrings 是两个不同的东西。你的问题是一个文档字符串。

标签： python markdown documentation restructuredtext

【解决方案1】：

Sphinx 可能是您正在寻找的，另外可以将生成的文档发布到您可能已经熟悉的ReadTheDocs。

任何.rst 文件都可以使用pandoc 严格转换为.md（或任何其他格式），您可以在其中执行以下操作：

pandoc -f page.rst -t page.md

【讨论】：

但是 Sphinx 只生成 .rst 文件不是吗？我们可以使用将那些 .rst 文件转换为 markdown 吗？
@Arès 更新了我的答案。

【解决方案2】：

从 reStructuredText 生成 Markdown 似乎是一个不常见的组合。你会在Markdown output for Sphinx based documentation找到与你类似的问题

【讨论】：