PythonドキュメントのreStructuredTextに代わる本当の選択肢はありますか？
私はオープンソースをすぐに始めていますPythonプロジェクトを間もなく開始し、事前にdocstringsの記述方法を決定しようとしています。明らかな答えは、autodocでreStructuredTextとSphinxを使用することです。 really docstringsにコードを適切に文書化するというアイデアのように、Sphinxが自動的にAPIドキュメントを構築するようにします。
問題は、それが使用するreStructuredText構文です-レンダリングされる前は完全に判読できないと思います。例えば：
：param path：ラップするファイルのパス ：type path：str ：param field_storage：ラップする：class： `FileStorage`インスタンス ：type field_storage：FileStorage ：param temporary：ファイルインスタンス が破棄されたときにファイルを削除するかどうか ：type temporary：bool
reallyスローダウンし、その構文の乱雑さを理解するために1分かかる必要があります。私はGoogleの方がずっと好きです（ Google Python Style Guide ）。これは、上記に対応するものは次のようになります：
Args： path（str）：ラップするファイルのパス field_storage（FileStorage）：ラップするFileStorageインスタンス temporary（bool）：かどうかFile インスタンスが破棄されたときにファイルを削除するかどうか
方法より良いです！しかしもちろん、Sphinxはそれを持たず、「Args：」の後のすべてのテキストを1行でレンダリングします。
要約すると、このreStructuredText構文を使用してコードベースを汚す前に、独自のAPIドキュメントを作成するだけでなく、SphinxとSphinxを使用する実際の代替策があるかどうかを知りたいのです。たとえば、Googleスタイルガイドのdocstringスタイルを処理するSphinxの拡張機能はありますか？
GoogleスタイルとNumPyスタイルの両方のドキュメント文字列を解析し、それらを標準のreStructuredTextに変換する Sphinx拡張 を作成しました。
使用するには、インストールするだけです。
$ pip install sphinxcontrib-napoleon
そして、それをconf.pyで有効にします：
# conf.py
# Add autodoc and napoleon to the extensions list
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon']
ナポレオンに関する詳細なドキュメント here 。
現時点でpythonプロジェクトを文書化するためにsphinxより良いものはないと思います。
より明確なdocstringを得るには、_ sphinx とともにnumpydocを使用するのが私のお気に入りです。あなたの例に基づいて、これは次のようになります：
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
（完全な例は ここ です）、HTML出力は これ のようになります
Rstファイルの構造はより明確で読みやすいと思います。 guide は、さらに多くの情報と規則を提供します。 numpydoc拡張機能はautodocでも機能します。
私は 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の使用を検討することもできます（ただし、現時点で積極的にメンテナンスされているわけではありません）。
実際、 reStructuredText および PEP8 のスタイルガイドは、多くのサードパーティプログラマーがそれに準拠しているにもかかわらず、ほとんどがPythonの標準ライブラリ自体のコーディングに適用されます。上手。
Googleの引数のスタイルは、コード内の観点からははるかに優れていることに同意します。しかし、あなたは sphinx でそのようなdocstringを生成することもできるはずです、 新しい行とインデントを保持して 。ただし、 ほどニースは出力されませんが、よりスフィンクなフォーマット を使用しています。
とにかく、スフィンクスを使用する必要はありませんところで、スフィンクスのautodocモジュールは間違いなく小さな部分ですそれの。 Epydoc （ epytext および reStructuredTextをサポートする）など、docstringのコンテンツを取得できる任意のドキュメントジェネレーターを仮想的に使用できます。 JavadocまたはPlaintext ）または pydoctor 、あるいは Doxygen のようなより普遍的なものです。
しかし、間違いなく、sphinxは非常にPythonicであり、Pythonで使用するのに非常に便利で、コードをPythonのエコシステムと一致させます。これは「欠けている」と思っているのは あなただけではありません 多分彼らは将来これらの不満を考慮に入れるかもしれません、あるいは多分あなたは自分でautodocモジュールを変更することを考えるかもしれません、それは非常に難しいことではありません、それはPythonで、それは良い練習になるでしょう。
あなたはcan好きなフォーマットでドキュメント文字列を書きます。ただし、他のすべてのPythonプログラマーのために、彼らがすでに知っているマークアップとツールを使用するのが最善です。reSTとSphinxに固執すれば、彼らの生活はより簡単になります。
Pythonは、docstringの内容を、関数/クラス/変数オブジェクトにアタッチされた__doc__属性として利用できるようにします。
したがって、ドキュメントを好きな形式から好きな形式に変換するPythonプログラムを簡単に書くことができます。JavadocスタイルやXMLなどを使用することもできます。
ちなみに、SphinxはPythonで記述されているため、非RST入力を受け取るようにするには、少量のPythonコードを記述するだけです。
新しい行を開始し、各変数名の後にタップを追加するだけです。次に、連続した太字の変数名で数行にレンダリングされます。
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