問題タブ [numpydoc]

注: 後に追加: numpydoc が機能するようになりました。これはpython 2の問題でもありました。私はそれで2to3を実行しましたが、今はうまくいっているようです。

OK、Sphinx 拡張機能を動作させるために 1 日を費やしましたが、誰かが私が間違っていることを指摘してくれることを期待しています。(申し訳ありませんが、これは少し長くなりますが、より多くの情報が私のやり方の誤りをすばやく見つけるのに役立つかもしれません)。

Sphinx は宣伝どおりに動作しているようですが、NumPy スタイルのドキュメントを使用したいので、numpydoc をインストールすることにしました。問題が発生した場合に備えて、私は Python 3.3 (Windows 7 で winpython 64 ビット) を使用しています。ここの指示から始めましたが、エラーが発生しました：

numpydoc.numpydoc No Diceを使って回避した人がいることがわかったグーグル。関連する可能性のあるすべてのものがパスにあることを確認しました（さらに、スフィンクスのファイルの sys.path に追加されましたconf.py）。numpydoc を sphinx の ext フォルダーにコピーして、それに応じて拡張文字列を変更しようとしましたが、まだ運がありません。

この時点で numpdoc をあきらめ、ナポレオンを試すことにしました。インストールの指示に従ってpip install sphinxcontrib-napoleonください。しかし、悲しいかな、ナポレオンは 3 ではなく 2.x にあるようです (ただし、卵はSphinx-1.1.3-py3.3.egg-info、インストール中にsphinxcontrib_napoleon-0.2.1-py3.3-nspkg.pth.再帰が深すぎるというエラーが発生します。

そこで、sphinx に拡張機能をインストールできるかどうかを確認することにしました。私は本質的に無作為に何かを見つけます。要求どおりにインストールしますが、今度は relpath エラー ( ValueError: path is on mount 'C:', start on mount 'D:') が原因で失敗します。これは、python インストールが C にあるのに、文書化しようとしているコード (および sphinx を実行しようとしている場所) が D にある (および Windows を実行している) ことは不幸なことです。

それで、たまたま問題のある拡張機能を 3 つ選んだだけですか? または、そうでない場合、私は何を間違っていますか? (さらに重要なことに) どうすれば正しく動作させることができますか?

PS 私は Python にまったく慣れていないので、信じられないほど愚かで基本的なエラーを犯しているとは思わないでください。

このチュートリアル、この質問、およびnumpy docstring standardを読んだにもかかわらず、sphinx autodoc で numpy docstring をうまく処理できません。

私conf.pyは持っています：

私のdocファイルには次のものがあります：

どこpython_file.pyにある：

走るmake htmlとERROR: Unknown directive type "autosummary". したがって、次のように追加autosummaryするとextensions：

私は得る：

この質問で推奨されているように、私はに追加numpydoc_show_class_members = Falseしますconf.py。

make htmlエラーなしで実行できるようになりましたが、 ParametersandReturnsセクションは numpydoc セクションとして解釈されません。

この混乱から抜け出す方法はありますか？

numpy/scipy ドキュメントへのガイドの規則に従って、関数パラメーターは次の方法でドキュメント化する必要があります。

type がintやstrなどの個別の型である場合、これは簡単です。

ここで、パラメーターをBaseClassのインスタンスにするか、同じインターフェイスを公開する任意のオブジェクト ( BaseClassから派生したクラスなど) にする必要があります。パラメータxが特定のインターフェイスを (派生またはダックタイピングによって) 公開する必要があることを簡潔に文書化する方法はありますか?

モジュールを文書化するために ( and と組み合わせて) を使用しようとしていますが、基本的なセットアップの後、実行するsphinxと、docstrings が含まれていない基本的な html のみが生成されます。私は Python 3.3 を実行しています。プロジェクト構造の概要は次のとおりです。autodocnumpydocmake html

__init__.py空で、追加conf.pyしたdocs/sourceディレクトリにありますsys.path.insert(0, os.path.abspath('../..'))

ディレクトリで実行make htmlするとdocs、次の出力が得られます。

それで、私は何を間違っていますか？

Numpy プロジェクトは、読みやすさと自動抽出をサポートするために、ドキュメントのフォーマットの仕様を提供しています (リンク)。また、いくつかの追加キーワードの抽出をサポートするために、Sphinx の拡張機能としてNumpydocも提供しています。

docutils の拡張機能を書き始める前に、既存の docstring をイントロスペクトし、Numpy 標準への非準拠を特定するのに役立つライブラリが存在しますか?

Numpy ドキュメンテーション仕様を採用したい広範なドキュメンテーションを備えた、より成熟したライブラリをイメージします。1 つのアプローチは、ライブラリをイントロスペクトし、ドキュメント文字列の状態を説明するレポートを生成することです。

これは、docutils または numpydoc の拡張としてこれを実装する前の偵察用の質問です。既存のソリューションを見逃していませんか、それとも洗練されたソリューションは存在しますか?

Spyder IDE (Mac OS では v.2.1.11) を使用していくつかのコードを書いています。関数の DocString (NumpyDoc 形式) を書いているときに、Spyder Object Inspectorがインデントされた行を書式設定する理由がわかりません。この奇妙な方法。

以下のような Docstring の場合、「Calc'd by Sellmeier...」の後の紙の参照がインデントされ、奇妙な動作が発生します。

上記の DocString は、次の出力 (Spyder の「オブジェクト インスペクター」/ヘルプ パネルのスクリーンショット) を生成し、「 MJ Mondry, DI Babic...」テキストに予期しない太字とインデント/リスト番号が表示されます。

インデントを削除しながら、次のようにします。

次のように、正常に見えます。

それは Spyder の単なるバグですか、それともインデントの他の意図的な使用ですか? Spyder IDE でさまざまな種類の書式設定を生成するためにインデントを使用する (または使用しない) 方法 (NumpyDoc 形式であると想定しています) NumpyDoc Documentation Page
で、インデントと自動リストに関する議論が見当たりません。

ここで利用できるドキュメント化されていない便利な DocString 機能があるかどうか疑問に思っています。(別の注意として、DocString の "References" セクションを使用できることに気付きました。これは、ある時点で Ref をそこに移動します。)

ありがとう！

私のバージョンは次のとおりです: Spyder v2.1.11、Python 2.7.6、Qt 4.8.4、PyQt4 (API v2) 4.9.6 on Darwin、Mac OS 10.10.2

sphinx でモジュールの要約テーブルを作成するのに問題があります。ファイルに追加sphinx.ext.autosummaryし、使用しています。Sphinx は、クラスの属性とメソッドの要約テーブルを作成するようですが、クラスを含むモジュールの要約テーブルを作成しません。conf.pynumpydoc

これをテストするために、最小限の作業例 (MWE) を作成しました。MWE プロジェクトには、__init__.pyインポートする と がありgeneric_moduleます。の内容は次のgeneric_moduleとおりです。

Sphinx 自動ドキュメントfoo、bar、およびonetwo. また、 のメソッドの優れた要約も作成されonetwoます。ただし、 のページの上部に要約テーブルは作成されませんgeneric_module。

ここ.. autosummary::に記載されているように、自分のgeneric_module.rstファイルに追加できることを知っています。ただし、モジュールを機能させるには、モジュールのすべての関数をリストする必要があります。私は拡張機能が私のためにこれを行うことができると思います.autosummary

複合Pythonデータ型のより正確な仕様を提供するためのSphinxの標準またはベストプラクティスはありますか? たとえば、dictマッピングstrを返す関数があり、スタイルstrを使用しています。numpydoc次のようなことをする必要があります:

またはおそらくdict of str: str？

コンテンツのタイプがわかっているリストの場合、NumPy が次の形式を使用していることに気付きました

この一般的なユース ケースに従うべき標準またはベスト プラクティスはありますか?

Numpydoc スタイルで文書化されている次の関数があり、文書がSphinx autofunction ディレクティブで自動生成されているとします。

非表示の引数をパブリック API の一部として宣伝したくありませんが、自動生成されたドキュメントに表示されます。関数への特定の引数を無視するように Sphinx に指示する方法はありますか、または (さらに良いことに) 先頭にアンダースコアが付いた引数を自動的に無視するようにする方法はありますか?