我有一个使用 epydoc 记录的项目。现在我正在尝试切换到狮身人面像。我为 epydocs 格式化了所有文档字符串，使用 B{}、L{} 等进行粗体、链接等，并使用@param、@return、@raise 等来解释输入、输出、异常等。
所以现在我改用 sphinx，它失去了所有这些功能。有没有一种自动化的方法可以将 epydocs 格式的文档字符串转换为 sphinx 格式的文档字符串？
【问题讨论】：
标签： python converter python-sphinx docstring epydoc
为了扩展 Kevin Horn 的答案，可以在由 autodoc-process-docstring 事件触发的事件处理程序中动态翻译文档字符串。
下面是一个小演示（通过将代码添加到 conf.py 来尝试）。它将一些常见的Epytext fields 中的@ 字符替换为:，在对应的Sphinx fields 中使用。
import re
re_field = re.compile('@(param|type|rtype|return)')
def fix_docstring(app, what, name, obj, options, lines):
for i in xrange(len(lines)):
lines[i] = re_field.sub(r':\1', lines[i])
def setup(app):
app.connect('autodoc-process-docstring', fix_docstring)
【讨论】：
Pyment 是一个可以转换 Python 文档字符串并创建缺失的骨架的工具。它可以管理 Google、Epydoc（javadoc 风格）、Numpydoc、reStructuredText（reST，Sphinx 默认）文档字符串格式.
它接受单个文件或文件夹（也探索子文件夹）。对于每个文件，它将识别每种文档字符串格式并将其转换为所需的格式。最后，将生成一个补丁以应用于该文件。
键入以下内容（您可以使用 virtualenv）：
$ git clone https://github.com/dadadel/pyment.git
$ cd pyment
$ python setup.py install
您可以通过执行以下操作将您的项目转换为 Sphinx 格式 (reST)，这是默认输出格式：
$ pyment /my/folder/project
【讨论】：
__doc__ 字符串，并且像B{Some bold text} 这样的Epydoc 标记仍保留在.patch 文件中。这是预期的吗？
__doc__ 问题呢？
理论上，您可以编写一个 Sphinx 扩展，它可以捕获读取文档字符串时触发的任何事件（source_read，也许？）并即时翻译文档字符串。
我说理论上是因为：
您也可以尝试用 Sphinx 之外的类似翻译器替换代码中的所有文档字符串，可能使用 ast 模块或类似的东西。
【讨论】：
作为建议的评论之一，sphinx-epytext 确实提供了相关支持。它对我有什么作用：
安装非常简单：
pip install -U sphinx-epytext
它包含一个文件process_docstring.py，通过将@ 替换为冒号:，将epytext 标记转换为reStructuredText 标记。
我发现其中缺少的一些字段是：ivar, var, cvar, vartype
只需在其中扩展现有列表 FIELDS：
FIELDS.extend(['ivar', 'var', 'cvar', 'vartype'])
Epytext 理解 @type 的变量，但 sphinx 理解 :vartype。
要解决这个问题，请在 process_docstring 方法中将之前的替换为后面的。
Sphinx 无法理解的大部分语法或文档字符串部分都被报告为警告。您可以通过运行sphinx-build 和-w <WarningLogFile> 来记录这些警告。根据我的经验，Sphinx 对字段应该如何开始或结束、缺少格式和语法等非常敏感。
【讨论】：