10

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

所以现在我切换到狮身人面像它失去了所有这些功能。是否有一种自动方法可以将 epydocs 格式的文档字符串转换为 sphinx 格式的文档字符串？

4

4 回答 4

7

为了扩展 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)
于 2012-10-29T18:24:58.633 回答
6

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)：

$ pyment /my/folder/project
于 2014-06-24T07:52:52.497 回答
1

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

我说理论上是因为：

  1. 很久以前就一直想写这样的东西，但是一直没搞定。
  2. 翻译这样的东西总是比看起来更难。

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

于 2012-10-25T18:49:03.530 回答
1

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

于 2018-08-09T20:18:17.660 回答