自动从epydoc的文档字符串格式切换到sphinx文档字符串格式？

Question

我有一个使用epydoc进行文档记录的项目。现在我正试着换成斯芬克斯。我为epydocs设置了所有文档字符串的格式，使用B{}、L{}等进行加粗、链接等操作，并使用@param、@return、@raise等来解释输入、输出、异常等。

所以现在我切换到了sphinx，它失去了所有这些特性。有没有一种自动的方法将epydocs格式的文档字符串转换为sphinx格式的文档字符串？

Answer 1

要扩展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)

Answer 2

是一个可以转换Python文档字符串和创建缺失的骨架的工具。它可以管理Google，Epydoc (javadoc风格)，Numpydoc，reStructuredText (reST，Sphinx default)文档字符串格式。

它接受单个文件或文件夹(也可以探索子文件夹)。对于每个文件，它将识别每个文档字符串格式并将其转换为所需的格式。最后，将生成一个补丁以应用于该文件。

要转换您的项目：

• install Pyment

键入以下内容(您可以使用virtualenv)：

$ git clone https://github.com/dadadel/pyment.git
$ cd pyment
$ python setup.py install

从Epydoc到Sphinx的

• convert

您可以通过执行以下操作将项目转换为Sphinx格式(reST)，这是默认的输出格式：

$ pyment /my/folder/project

Answer 3

从理论上讲，您可以编写一个Sphinx扩展，它将捕获在读取文档字符串时触发的任何事件(也许是source_read？)并在飞行中翻译文档字符串。

我说在理论上是因为：

1. 我一直想写这样的东西很长一段时间了，但是还没来得及实现，像这样的东西总是比看起来难。

您还可以尝试在Sphinx之外使用类似的翻译器替换代码中的所有文档字符串，比如使用ast模块或类似的东西。