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

Question

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

所以现在我改用 sphinx 它失去了所有这些功能。 有没有一种自动的方法可以将为 epydocs 格式化的文档字符串转换为为 sphinx 格式化的文档字符串？

Answer 1

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

下面是一个小演示（通过将代码添加到conf.py来尝试）。 它将一些常见的Epytext 字段中的@字符替换为: ，用于相应的Sphinx 字段中。

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

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

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

要转换您的项目：

• 安装 Pyment

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

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

• 从 Epydoc 转换为 Sphinx

您可以将项目转换为 Sphinx 格式 (reST)，这是默认的 output 格式，方法是：

$ pyment /my/folder/project

Answer 3

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

我说理论上是因为：

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

您也可以尝试用 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 无法理解的大部分语法或文档字符串部分都被报告为警告。 您可以通过使用-w <WarningLogFile>运行sphinx-build来记录这些警告。 根据我的经验，Sphinx 对字段应该如何开始或结束、缺少格式语法等非常敏感。