pip を用いてインストールします。make も必要です。
# yum install -y make # pip3 install sphinx
まずは、.rst ファイルのみを使用した静的なドキュメントを作成してみます。sphinx-quickstart を用いてプロジェクトを作成してください。
$ mkdir work $ cd work $ sphinx-quickstart > Separate source and build directories (y/n) [n]: y > Project name: テストドキュメント > Author name(s): 山田太郎 > Project release []: 1.0.0 > Project language [en]: ja
下記のコンテンツファイル(*.rst)を作成してください。
$ mkdir -p ./source/test $ vi ./source/test/test1.rst $ vi ./source/test/test2.rst
****************************** Sphinxサンプル1 ****************************** これはSphixのサンプルです。
****************************** Sphinxサンプル2 ****************************** これはSphixのサンプルです。
作成したコンテンツファイルを index.rst に登録してください。
.. toctree:: :maxdepth: 2 :caption: Contents: /test/test1 /test/test2
make html で複数HTMLファイル形式にビルドします。
$ make html $ ls -l ./build/html/
./build/html/ ディレクトリ配下に HTML ファイルが生成されます。これをブラウザで開くと、生成されたドキュメントを表示することができます。
単一HTMLフォーマットでビルドするには、html の代わりに singlehtml などのフォーマット名を指定します。
$ make singlehtml $ ls -l ./build/singlehtml/
生成可能なフォーマットの一覧は make help を参照してください。
$ make help
conf.py を編集して再ビルドすることでテーマを変更することができます。
html_theme = 'pyramid'
標準テーマの他に、テーマを追加インストールして使用することもできます。
$ pip3 install sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
指定可能なテーマの一覧は下記などを参照してください。
Python の docstring を組み込むために、./source/conf.py に設定を行います。sys.path には conf.py から見た、Python ソースファイルの格納先を指定します。
# コメントインして Python ソースファイルのディレクトリを参照する import os import sys sys.path.insert(0, os.path.abspath('../src/')) : # 必要な拡張機能を読み込む extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', ]
対象とするPythonソースコードを作成します。
$ mkdir ./src $ vi ./src/test3.py
class Test3Class:
"""テスト3クラス
"""
def add(self, x, y):
"""値Xと値Yの和を求める
Args:
x (int): 値X
y (int): 値Y
Returns:
int: 値Xと値Yの和
"""
return x + y
index.rst に test3 を追加します。
/test/test1 /test/test2 test3
sphinx-apidoc を用いて modules.rst と test3.rst を生成します。これらのファイルは必要最低限の情報のみを含みます。実際に docstring からコメントを抽出する作業はビルド時に行います。
$ sphinx-apidoc -f -o ./source/ ./src $ make html
./build/html/ 配下に test3.py のマニュアルを含む HTML ファイル群が生成されます。