從 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 對字段應該如何開始或結束、缺少格式語法等非常敏感。