問題タブ [sphinx-apidoc]

Sphinx を使用して、私が取り組んできた Python ライブラリを文書化しようとしています。途中でこの投稿を大まかなガイドとして使用してきました。しかし、Sphinx を正しく動作させるのに問題があります。

すべての設定が完了したら、Sphinx がインストールされ、プロジェクトのルートから入力するコードにドキュメントを追加しました。

出力：

次に、docs/conf.py をそれぞれ編集して、sys.path.insert(0, os.path.abspath('/Users//path/to/mypackage')) が正しいことを確認します。

ただし、次の方法で（docsディレクトリ内から）ドキュメントをビルドしようとすると：

私は次のように迎えられます：

私は sphinx-apidoc を使用し、他のライブラリで html を作成しましたが、これに遭遇したことはないので、途方に暮れています。何かご意見は？

現在、 を実行するたびにsphinx-build、ソース ファイルに変更がある場合にのみ、インライン docstring が選択されて使用されます。スイッチで呼び出しsphinx-buildてみましたが、これは効果がないようです。-a

HTML 出力を強制的に完全に再構築し、autodoc を強制的に実行するにはどうすればよいですか?

Sphinx を使用して、現在十分に文書化されていない大規模なプロジェクトを文書化したいと考えています。sphinx-apidoc特に、コードをドキュメント化する際に、コードからドキュメントを生成するために使用したいと考えています。

ただし、プロジェクトの使用方法などに関するチュートリアルのページもいくつか用意したいのですが、呼び出すsphinx-apidocとドキュメント全体が一度に生成されるようです。

私の質問は次のとおりです。手動で作成するチュートリアル ページを作成し、同時にコード内のドキュメントを更新できる正しいワークフローは何ですか? 手動で作成したチュートリアル ページ (たとえば に含まれているものindex.txt) を更新して実行するsphinx-apidocと、ドキュメント全体が一度に生成されるため、それらが失われることに注意してください。

一般に、ドキュメントの作成を進める方法に関するガイドラインはありますか?

注:基本的な手順では、すべてのコード ドキュメントが既に配置されていることを前提としており、ドキュメントの作成を進めても更新は行われないため、不都合が生じます。少なくともこれは私が解決する必要があるものです。

Python でパッケージを文書化しようとしています。現時点では、次のディレクトリ構造があります。

このツリーは の起動の結果ですsphinx-quickstart。私はconf.pyコメントを外しsys.path.insert(0, os.path.abspath('.'))、私は持っていextensions = ['sphinx.ext.autodoc']ます。

私index.rstは：

すべての__init__.py's には docstring があり、同じことがモジュールfoo.pyおよびbar.py. ただし、make htmlプロジェクトで実行すると、ドキュメントが表示されません。

質問の背景:

django プロジェクトで sphinx を使用してドキュメントを作成し、django コード コメントを使用してドキュメントを自動作成したいと考えています。

これで、django(1.9) プロジェクトができました。ファイル構造は次のとおりです。

次に、ご覧のとおり、 Sphinx doc プロジェクトdocsを保持するフォルダーを内部に配置します。

これで、*.rstファイルとbuild html.

しかしautodoc、コンテンツを試してみると、失敗します。

以下は私がしたことです：

まず、これらをdocs/conf.pyref: https://stackoverflow.com/a/12969839/2544762に追加しました。

次に、sphinx-apidocアクションを作成しました。

その後、 でいくつかのファイルdocs/documentationsを取得しました。.rst

その後、私は実行しmake html、次のように警告します:

私は何を間違えましたか？django コードを使用してドキュメントを作成するにはどうすればよいですか?