58

私はまもなくオープンソースの Python プロジェクトを開始し、docstring の書き方を事前に決めようとしています。明らかな答えは、reStructuredText と Sphinx を と一緒autodocに使用することです。なぜなら、コードを docstring に適切にドキュメント化してから、Sphinx に API ドキュメントを自動的に作成させるというアイデアが本当に好きだからです。

問題は、それが使用する reStructuredText 構文です。レンダリングされる前は完全に判読できないと思います。例えば：

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File instance
    is destructed
:type temporary: bool

その構文のごちゃまぜから何らかの意味を理解するためには、本当に速度を落として少し時間を割かなければなりません。私は、Google のやり方 ( Google Python Style Guide )の方がずっと好きです。

引数:
    path (str): ラップするファイルのパス
    field_storage (FileStorage): ラップする FileStorage インスタンス
    temporary (bool): ファイルが削除されたときにファイルを削除するかどうか
        インスタンスが破棄される

ずっといい！しかしもちろん、Sphinx にはそれがなく、すべてのテキストArgs:を 1 つの長い行でレンダリングします。

要約すると、この reStructuredText 構文を使用してコード ベースを汚す前に、独自の API ドキュメントを作成する以外に、この reStructuredText 構文と Sphinx を使用する実際の代替手段があるかどうかを知りたいと思います。たとえば、Google スタイル ガイドの docstring スタイルを処理する Sphinx の拡張機能はありますか?

4

7 に答える 7

32

I don't think that there is something better than sphinx for documenting python projects at the moment.

To have a clearer docstring my favorite choice is using sphinx together with numpydoc. Based on your example this would look like:

def foo(path, field_storage, temporary):
    """This is function foo

    Parameters
    ----------
    path : str
        The path of the file to wrap
    field_storage : :class:`FileStorage`
        The :class:`FileStorage` instance to wrap
    temporary : bool
        Whether or not to delete the file when the File instance
        is destructed

    Returns
    -------
    describe : type
        Explanation
    ...

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    ...
    """

    pass

(a full example is Here), HTML output will look like this

I think the structure of the rst-file is clearer and more readable. The guide gives some more information and conventions. The numpydoc extension works with autodoc as well.

于 2012-06-24T09:14:25.423 に答える
10

Sphinxではなくepydocを使用しているため、この回答は当てはまらない場合があります。

メソッドと関数を文書化するために記述した reStructuredText 構文は、可能な唯一のものではありません。これまでのところ、統合された定義リストを使用してパラメーターを記述することを好みます。これは、Google の方法と非常によく似ています。

:Parameters:
  path : str
     The path of the file to wrap
  field_storage: FileStorage
     The FileStorage instance to wrap
  temporary: bool
     Whether or not to delete the file when the File instance is destructed

sphix がサポートしている場合は試してみます。そうでない場合は、そのためだけに epydoc を使用することも検討できます (ただし、現在はそれほど積極的に保守されていません)。

于 2012-06-23T09:32:56.183 に答える
7

実際、reStructuredTextとPEP8のスタイルガイドは、多くのサードパーティプログラマーもそれに準拠していますが、主にPythonの標準ライブラリ自体のコーディングに適用されます。

Googleの引数のスタイルは、コード内の観点からはるかに優れていることに同意します。ただし、新しい行とインデントを保持したまま、スフィンクスを使用してこのようなdocstringを生成できるはずです。ただし、よりスフィンシーなフォーマットの場合ほどうまく出力されません。

とにかく、スフィンクスを使用する必要はありません。ちなみに、autodocスフィンクスのモジュールは間違いなくそのほんの一部です。Epydoc（epytext、reStructuredText、Javadoc、Plaintextをサポート）やpydoctor、さらにはDoxygenのようなより普遍的なものなど、docstringのコンテンツを取得できるドキュメントジェネレータを事実上使用できます。

しかし、間違いなく、sphinxは非常にPythonであり、Pythonでの使用に非常に便利であり、コードをPythonのエコシステムと一致させることができます。これが「不足」だと思っているのはあなただけではないと思います。将来的にはこれらの苦情を考慮に入れるかもしれませんし、autodocモジュールを自分で変更することを検討するかもしれませんが、それほど難しいことではないはずです。Pythonの場合は、良い演習になるでしょう。

于 2012-06-23T08:29:29.047 に答える
3

docstringは好きな形式で書くことができます。ただし、他のすべてのPythonプログラマーのために、彼らがすでに知っているマークアップとツールを使用するのが最善です。reSTとSphinxに固執すれば、彼らの生活は楽になります。

于 2012-06-23T08:29:40.397 に答える
2

Python は、docstring の内容を__doc__、関数/クラス/変数オブジェクトにアタッチされた属性として利用できるようにします。

したがって、ドキュメントを好きな形式から好きな形式に変換する Python プログラムを自明に書くことができます。Javadoc スタイルや XML などを使用することもできます。

ちなみに、Sphinx は Python で書かれているので、非 RST 入力を取るのは Python コードを少し書くだけです。

于 2012-06-23T07:26:42.810 に答える
0

新しい行を開始し、各変数名の後にタップを追加するだけです。次に、連続する太字の変数名を使用して複数の行にレンダリングされます。

Args:
    path (str):
        The path of the file to wrap
    field_storage (FileStorage):
        The FileStorage instance to wrap
    temporary (bool):
        Whether or not to delete the file when the File
        instance is destructed
于 2012-07-15T13:00:21.540 に答える