とほほのPython入門 - Sphinx

トップ > Python入門 > Sphinx

Sphinxとは

検証環境

Sphinxをインストールする

pip を用いてインストールします。make も必要です。

Shell
# yum install -y make
# pip3 install sphinx

静的コンテンツをドキュメント化する

まずは、.rst ファイルのみを使用した静的なドキュメントを作成してみます。sphinx-quickstart を用いてプロジェクトを作成してください。

Shell
$ 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)を作成してください。

Shell
$ mkdir -p ./source/test
$ vi ./source/test/test1.rst
$ vi ./source/test/test2.rst
./source/test/test1.rst
******************************
Sphinxサンプル1
******************************
これはSphixのサンプルです。
./source/test/test2.rst
******************************
Sphinxサンプル2
******************************
これはSphixのサンプルです。

作成したコンテンツファイルを index.rst に登録してください。

./source/index.rst
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   /test/test1
   /test/test2

make html で複数HTMLファイル形式にビルドします。

Shell
$ make html
$ ls -l ./build/html/

./build/html/ ディレクトリ配下に HTML ファイルが生成されます。これをブラウザで開くと、生成されたドキュメントを表示することができます。

複数HTML以外の形式にビルドする

単一HTMLフォーマットでビルドするには、html の代わりに singlehtml などのフォーマット名を指定します。

Shell
$ make singlehtml
$ ls -l ./build/singlehtml/

生成可能なフォーマットの一覧は make help を参照してください。

Shell
$ make help

テーマを変更する

conf.py を編集して再ビルドすることでテーマを変更することができます。

./source/conf.py
html_theme = 'pyramid'

標準テーマの他に、テーマを追加インストールして使用することもできます。

Shell
$ pip3 install sphinx_rtd_theme
./source/conf.py
html_theme = 'sphinx_rtd_theme'

指定可能なテーマの一覧は下記などを参照してください。

Pythonドキュメントを組み込む

Python の docstring を組み込むために、./source/conf.py に設定を行います。sys.path には conf.py から見た、Python ソースファイルの格納先を指定します。

./source/conf.py
# コメントインして Python ソースファイルのディレクトリを参照する
import os
import sys
sys.path.insert(0, os.path.abspath('../src/'))
  :
# 必要な拡張機能を読み込む
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
]

対象とするPythonソースコードを作成します。

Shell
$ mkdir ./src
$ vi ./src/test3.py
./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 を追加します。

./source/index.rst
   /test/test1
   /test/test2
   test3

sphinx-apidoc を用いて modules.rst と test3.rst を生成します。これらのファイルは必要最低限の情報のみを含みます。実際に docstring からコメントを抽出する作業はビルド時に行います。

Shell
$ sphinx-apidoc -f -o ./source/ ./src
$ make html

./build/html/ 配下に test3.py のマニュアルを含む HTML ファイル群が生成されます。


Copyright(C) 2019 杜甫々
初版:2019年10月20日、最終更新:2019年10月20日
http://www.tohoho-web.com/python/sphinx.htm