转换项目：

Question

我有一个项目，我使用epydoc记录。现在我正在尝试切换到狮身人面像。我为epydocs格式化了所有文档字符串，使用B {}，L {}等进行粗体，链接等，并使用@ param，@ return，@ raise等来解释输入，输出，异常等。

所以现在我转向sphinx它会失去所有这些功能。是否有自动方式将为epydocs格式化的文档字符串转换为为sphinx格式化的文档字符串？

Answer 1

为了扩展Kevin Horn的答案，文档字符串可以在autodoc-process-docstring事件触发的事件处理程序中即时翻译。

以下是一个小型演示（通过将代码添加到 conf.py 来尝试）。它会将@替换为:中的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)字符{{1}}，{{1}}用于相应的Epytext fields。

{{1}}

Answer 2

Pyment是一个可以转换Python文档字符串并创建缺失字符串的工具。它可以管理 Google ， Epydoc （javadoc样式）， Numpydoc ， reStructuredText （reST，Sphinx默认）docstring格式

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

转换项目：

安装Pyment

键入以下内容（您可以使用virtualenv）：

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

从Epydoc转换为Sphinx

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

$ pyment /my/folder/project

Answer 3

理论上你可以编写一个Sphinx扩展，它可以捕获在读取文档字符串时被触发的任何事件（source_read，也许？）并动态翻译文档字符串。

我在理论上说因为：

我一直想写这样的东西很长一段时间，但还没有设法解决它。
翻译这样的东西总是比它看起来更难。

您也可以尝试用Sphinx之外的类似转换器替换代码中的所有文档字符串，可能使用ast模块或类似的东西。

Answer 4

正如评论之一所建议，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对字段应该如何开始或结束，缺少格式语法等非常敏感。

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

4 个答案:

转换项目：