10

私は、epydoc を使用して文書化したプロジェクトを持っています。今、私はスフィンクスに切り替えようとしています。太字やリンクなどに B{}、L{} などを使用し、入力、出力、例外などを説明するために @param、@return、@raise などを使用して、epydocs 用にすべてのドキュメント文字列をフォーマットしました。

そのため、Sphinx に切り替えると、これらの機能がすべて失われます。epydocs 用にフォーマットされた docstring を sphinx 用にフォーマットされた docstring に自動的に変換する方法はありますか?

4

4 に答える 4

7

Kevin Horn の回答を拡張するために、docstring は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 に答える
1

理論的には、docstring が読み取られたときに発生するイベントをキャッチする Sphinx 拡張機能を作成し ( source_read、多分?)、その場で docstring を変換することができます。

私は理論的に次の理由で言います：

  1. 私は長い間そのようなことを書きたいと思っていましたが、まだそれを実現できていません.
  2. このようなものを翻訳することは、見た目よりも常に困難です。

また、コード内のすべての docstring を、おそらくastモジュールまたは類似のものを使用して、Sphinx の外部にある同様のトランスレータに置き換えることもできます。

于 2012-10-25T18:49:03.530 に答える