この記事では、Pythonコード内のdocstringからドキュメントを生成するための（非常に）基本を説明します。 それは挽くのビットですが、一度それを行った後、すべての新しいプロジェクトでプロセスを繰り返すことは容易になります。

私たちの目的のために、(1)コードを文書化することの価値を信じていること、(2)docstringsからドキュメントを生成したいこと、(3)作業を達成するためにSphinxを使

最後に、アプリケーション用に個別の仮想環境を既に設定していることを前提としています。 興味のある人のために、私は本当にpyenv環境マネージャーが好きです。 それも便利なインストーラを持っています。pip経由でsphinxをインストールする必要があります。 最低でもバージョン1.3が必要ですが、正当な理由がない限り、最新バージョンをインストールする必要があります。

$ pip install sphinx

ステップ2:クイックスタートでプロジェクトを設定する

sphinxパッケージをインストールすると、いくつかのコ

そのうちの1つ、sphinx-quickstartは、ドキュメントの基本的な設定ファイルとディレクトリ構造をすばやく生成します。

プロジェクトのベースディレクトリ（つまり、Git repo root）でこのコマンドを実行します。 それはそれが行為である定めるいくつかの質問をする。 通常、デフォルト値を受け入れることができますが、デフォルト値から逸脱する場合のいくつかの提案があります。

プログラムの実行後、新しい./docsconf.pyindex.rstMakefile。

ステップ3：調整します。conf.py クイックスタートユーティリティによって生成されたデフォルトのconf.pyファイルの長さは約170行なので、ここにはすべてを含めません。 ただし、続行する前に更新する必要がある項目がいくつかあります。最初に行う必要があるのは、プログラムコードを含むPythonパッケージがconf.pyファイルと関連している場所を示すことです。 ディレクトリ構造が次のようになっている場合:P>

conf.pyファイルに、pythonパッケージを見つけるためにsphinxが一つのディレクトリレベルを”上”に行かなければならないことを示す必要があります。

これを置く場所は、設定ファイルの最初のセクションの最後にあります。 General Configurationconf.pyファイルと同じディレクトリにあることを示します。 これを次のように変更する必要があります。

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Sphinx拡張のリストに”Napoleon”を追加して

を使用するには、sphinxは従来のreStructuredTextで書かれたdocstringのみを理解します。 あなたがそのようなdocstringを扱う特権を持っていたなら、あなたはそれらが書くのが苦痛であり、ソースコードでそれらを直接見るときに読むのが人間にNapoleon拡張機能により、Sphinxは他の2つの一般的な形式で書かれたdocstringを理解することができます：NumPyとGoogle。私たちがしなければならないのは、sphinx.ext.napoleonextensionsリストに追加することだけです。 完了したら、次のようになります。

extensions = 

ステップ4：インデックスを更新します。rst

この時点で、実際にビルドプロセスを実行してドキュメントを生成することができます。 しかし、それはかなり残念になります。 ここでは、私たちが得るだろうものです:div>

のステップ

私たちはここで表面を傷つけましたが、私たちの簡単なドキュメントにはまだたくさんの疣贅があります。

このトピックの次の記事では、autodoc拡張機能のディレクティブについて深く掘り下げ、ドキュメントの内容と外観をより詳細に制御します。