私は Python API を作成しており、Google docstring規則を使用してソース内のすべてのクラスと関数を文書化しました。これは、Sphinx 規則よりもはるかに読みやすいことがわかりました。Sphinx を使用して API のドキュメントを作成したいと考えています。NumpydocとGoogle docstringsをサポートするNapoleonという拡張機能があるので、それを使用してみましたが、いくつか問題が発生しました。Ubuntu 12.04 で Python 2.7.3 を使用しています。
Sphinx 1.1.3 がインストールされています。ドキュメントの最初のステップを実行しました（sphinx-quickstart有効autodoc化されたmakeファイルを使用）。Sphinx 1.3 より前は、ドキュメントsphinxcontrib.napoleonの に拡張機能として追加する必要があったことを読みました。conf.py私はそれを行い、拡張機能napoleonが見つからないというエラーを受け取りました。ダウンロードしてインストールしたところ、特定のパッケージが見つからないというエラーが発生しました。
拡張 sphinxcontrib.napoleon をインポートできませんでした (例外: 名前 6 をインポートできません)
これは要件ファイル内のパッケージの名前だったので、インストールしました。別のパッケージでも同じエラーが発生したため、それもインストールしました。同じエラーが発生しましたが、「範囲」があります。
拡張 sphinxcontrib.napoleon をインポートできませんでした (例外: 名前範囲をインポートできません)。
どのパッケージかわかりません。どこにも見つからないので、行き詰まっています。念のため「sphinx.ext.napoleon」を試してみましたが、予想通り拡張子が見つかりませんでした。
そこで、Sphinx 1.3 と、Sphinx に同梱されている「sphinx.ext.napoleon」で試してみました。apt-get でインストールすると、更新後もバージョン 1.1.3 しか取得できません。そのため、Sphinx 1.3 を直接ダウンロードしてインストールしようとしましたが、次のエラーが発生しました。
Processing ./Sphinx-1.3.4.tar.gz Complete output from command python setup.py egg_info: /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'entry_points' warnings.warn(msg) /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'extras_require' warnings.warn(msg) /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'include_package_data' warnings.warn(msg) /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'zip_safe' warnings.warn(msg) /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'install_requires' warnings.warn(msg)
setuptools に問題があるようです。この投稿を見つけて解決策を試しましたが、うまくいきません。
すべての docstring を変更できることはわかっていますが、それには時間がかかり、読みにくくなります。Sphinx 以外のものを試すこともできますが、Sphinx は Python の最も一般的なドキュメント ツールです。
ソース内のGoogle docstringから作成された適切なドキュメントを (まだ自動的に) 取得するにはどうすればよいですか?