PythonコードのドキュメントをdocstringとSphinxを用いて自動生成する方法

 本投稿は,Pythonでのコーディングに対し,そのドキュメントを自動生成する方法に関する投稿です.docstring形式で記述したコード中のコメントを,Sphinxを用いてWebサイト形式のドキュメントを自動生成します.また,コード中のコメントを利用したドキュメン自動生成だけでなく,軽量マークアップ言語を用いて手書きする方法も紹介します.

 本投稿で使用したPCのOSはWindows 11 23H2,Pythonのバージョンはv3.10.11,Sphinx(sphinx-quickstart)のバージョンはv8.1.3です.
 本投稿でPythonのv3.10.11を用いている理由は,第6.2節でのimport文の記法に伴うトラブルシューティングの例示において,ライブラリPyCaretをimportする場合を扱っており,そのPyCaretが対応しているPythonのバージョンがv3.10.11だからです.
 PythonコードからSphinxを用いてドキュメント生成するだけであれば,例えば本投稿執筆時点で最新である,Python v3.13.1でも支障はありません(実際に,第1~5章までの執筆時点ではv3.13.1の環境で行っていました).

 本投稿で説明に用いた,Pythonモジュール(samplePython.py)や軽量マークアップ言語で手書きしたファイル(sampleRTS.rts)や,それらから生成したWebサイト形式のドキュメントを,筆者のGitHubアカウント[1]にて,公開しています.ただし,GitHubへのアップロード仕様の都合により,Pythonの仮想環境は省いてあります.

目次

  1. docstringとSphinxの概要
  2. Sphinxの環境構築
  3. コード中のコメントからドキュメント自動生成
  4. 非コードのドキュメント生成
  5. Sphinxの設定や軽量マークアップ言語などの記述方法
  6. トラブルシューティング

1. docstringとSphinxの概要

 docstringは,Pythonにおけるクラスや関数などの説明を記述するコメント文,そのフォーマットのことである.そのフォーマットにもいくつか種類があり,googleスタイルやNumPyスタイルなどがある.本投稿では,googleスタイルを用いている.

 Sphinxは,主にPythonモジュールのドキュメント作成を自動化するツールである.Pythonコード中にdocstringの記法で記述されたコメント文から.rstファイルを作成し,.rstファイルから.htmlファイルを作成することで,Webサイト形式のドキュメントを自動生成できる.

2. Sphinxの環境構築

 既にdocstring形式のコメントを記述したPythonモジュールがある前提で,ドキュメント自動生成を行うための環境構築について説明する.仮想環境に関する詳細は,過去の投稿[1]を参照されたし.

 コマンドプロンプトを起動し,コマンドを入力して仮想環境を作成する.作成するディレクトリは,任意のもので可能である.下記にコマンド例を示す.
 筆者は,CドライブはOS関連のファイル,Dドライブはインストールした各種ソフトウェアのように,ドライブを区別して使用している.そのため,下記例は,Dドライブ直下にSphinxフォルダを作成し,その内部に仮想環境を作成する場合の例である.
 以降,本投稿ではDドライブ直下にSphinxフォルダを作成した場合のパスで,説明を行う.

py -m venv D:\Sphinx

 前述したコマンド例のディレクトリで仮想環境を作成した場合の,仮想環境をactivateするコマンド例を以下に示す.

D:\Sphinx\Scripts\activate

 下記コマンドで,Sphinxをインストールする.

pip install sphinx Pillow

 インストール成否の確認として,下記コマンドでバージョン表示できるかを確認する.

sphinx-quickstart --version

 もしバージョン表示でエラーが生じた場合は,Sphinxのバージョンアップをすると解決する場合がある.バージョンアップのコマンドは下記の通りである.

pip install sphinx -U

 Sphinxで自動生成するドキュメントはWebページ形式(.htmlなどによる構成)のため,CSSでドキュメントのデザインを設定/変更することができる.実際にテーマの設定方法は,「Sphinxの設定」の観点で第5章にて後述する.この第2.4節では,設定するテーマをそもそもインストールする方法を,「環境構築/インストール」の観点でこの場に記述する.
 Sphinxで自動作成するドキュメント向けのテーマとして,その内の1テーマをインストールするコマンドを以下に例示する.

pip install sphinx_rtd_theme

3. コード中のコメントからドキュメント自動生成

 Pythonモジュールからドキュメント生成までのファイル変換工程は,「.pyファイル → .rstファイル → .htmlファイル」である.この第3章では,各工程の手順/方法を紹介する.

 仮想環境をactivateするコマンド例を以下に示す.

D:\Sphinx\Scripts\activate

 Pythonモジュールや,第3.3節で後述するconf.pyやindex.rstを格納するディレクトリへ移動する.ディレクトリはおよそ任意で可能だと思うが,筆者はSphinxフォルダを指定している.

cd D:\Sphinx

 もしコマンドプロンプト上のカレントディレクトリがCドライブであり,Dドライブなど別ドライブに移動したい場合は,コマンド “cd” におけるドライブ移動のオプション “/d” を加える必要がある.

cd /d D:\Sphinx

 conf.pyファイルは,作成するドキュメント全体の設定を記述したファイルである.index.rstファイルは,作成したWebページ形式のドキュメントにおいて,ドキュメント化の対象とするファイル(e.g. Pythonモジュールや,軽量マークアップ言語で手書きしたファイル)を列挙したファイルである.
 下記コマンドにより,conf.pyファイルやindex.rtsファイル,その他Web形式のドキュメント作成に必要なフォルダやファイルを作成する.

sphinx-quickstart docs

 上記コマンドにおける “docs” 部分は,作成するフォルダやファイルを格納するディレクトリである.第3.2節により,カレントディレクトリは “D:\Sphinx” であるため,”D:\Sphinx\docs” とその中に各種フォルダファイルが作成される.docsフォルダは,予め手動で作成しておらずとも,自動で作成される.
 上記コマンドを実行すると,対話形式でconf.pyに記述する設定を行う(図1).これらの設定は,conf.pyを直接書き換えることで変更可能である.

  • Pythonモジュールごとに.htmlファイルを分けて出力するか?
    • [y/n]で回答
  • ドキュメント/Webサイトの名前
  • 著者名
    • この著者名から,自動的にcopyrightの内容が作成されます
  • リリース
    • ドキュメントの対象となるPythonモジュール/プロジェクトの,バージョン/リリース番号
  • Webサイト上での言語
    • デフォルトは “en” で英語の設定
    • “ja” と入力すると日本語に設定できる
図1 対話形式でconf.py等を作成する様子

 conf.pyは, “D:\Sphinx\docs\source” のディレクトリに格納されている.編集内容を図2に示す.

# importの追加
import os
import sys
sys.path.insert( 0, os.path.abspath("./") ) # conf.pyが格納されているディレクトリを,PYthonモジュール検索パスに追加する
# extensionsへの加筆
extensions = [
    "sphinx.ext.autodoc", # docstring形式コメントを自動でドキュメント化するためのもの
    "sphinx.ext.napoleon" # googleスタイルのdocstringに対応させるためのもの
]
図2 編集したconf.pyの様子

 第3.3節で作成されたconf.pyに対し,図2のconf.pyはこの第4節で説明した最低限必要な記述の他にも加筆や変更が加えてある.
 加筆した”autodic_mock_imports” は,Pythonコード中のimport文に対しエラーが発生した場合の対策である.詳細は,トラブルシューティングの観点で,第6章にて後述する.
 変更を加えた “html_theme” は,Web形式のドキュメントにおける,テーマ(外観)の変更である.詳細は,Sphinxに関するさらなる設定の観点で,第5章にて後述する.

 index.rstは, “D:\Sphinx\docs\source” のディレクトリに格納されている.
 index.rstの “toctree” に,対象となるPythonモジュール名を記述することで,Webページ形式のドキュメント対象として見なされる.ファイル名を記述する際は,拡張子.pyを除き記述する.
 編集の様子を示した図3は, “samplePython.py” をWebページ形式のドキュメント対象とした場合の例である.

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   
   samplePython
図3 編集したindex.rstの様子

 Webサイト形式(.htmlファイル)のドキュメント生成に向け,対象のPythonモジュールに対し,.pyファイルから.rstファイルを作成する..rstファイルの作成は,下記コマンドでできる.

sphinx-apidoc -f -o ./docs/source ./

 上記コマンドにおいて,前半のディレクトリ(”.docs/source”)は,作成される.rstファイルの出力先を意味する.本投稿では,conf.pyが格納されているディレクトリと同じディレクトリを指定している.
 後半のディレクトリ(”./”)は,対象のPythonモジュールが格納されているディレクトリを意味する.ここで入力するディレクトリは,コマンドプロンプト上でのカレントディレクトリからの相対パスを意味する.
 .pyファイルから作成された.rstファイルは,sourceフォルダ内に格納される.

 以下に,ディレクトリの概況を示す.

D:\Sphinx
├─ docs
│ ├─ build
│ └─ source
│   ├─ conf.py
│   ├─ index.rst
│   └─ samplePython.rst
└─ samplePython.py

 次の第3.8節では,.htmlファイルを作成する.それに向け,コマンドプロンプト上でのディレクトリを,下記コマンドで移動する.

cd D:\Sphinx\docs

 下記のコマンドを実行すると,ディレクトリ “D:\Sphinx\docs\build\html” に,対象となるPythonモジュールの.htmlファイルが格納される.また,このhtmlフォルダには,Pythonモジュールから作成した.htmlファイルの他,第4章で説明する,軽量マークアップ言語で手書きしたファイルから作成した.htmlファイルなど,全ての.htmlファイルが格納される.
 そして,このhtmlフォルダ内にあるindexファイルが,いわゆるホームページに該当する.

make html

 index.htmlからホームページを開くと,ページ内の左側にあるCONTENTS欄に,作成したドキュメントが列挙されている.作成したsamplePython.pyのドキュメントの様子を,図4に示す.

図4 Pythonモジュール中のdocstring形式コメントから自動生成したドキュメント

 Pythonモジュールに変更があった際は,下記に挙げる,これまで前述してきた内容を再び実行すれば,更新内容が反映されたドキュメントが新たに生成される.

  • 第3.1節:仮想環境のactivate
  • 第3.2節:SPhinxフォルダのディレクトリの移動
  • 第3.6節:対象Pythonモジュールに対する.rstファイルの作成(=新たに上書き保存される)
  • 第3.7節:sourceフォルダのディレクトリへ移動
  • 第3.8節:.htmlファイルの作成

4. 非コードのドキュンメント生成

 第4章では,コードが記述されたPythonモジュールから.rstファイルを介しドキュメント生成した代3章とは異なり,ドキュメントの内容を.rstファイルに軽量マークアップ言語で直接記述し,非コードからドキュメントを生成する方法を紹介する.

 作成したいドキュメントの.rstファイルを.rstファイルで用意する方法は,.txtファイルを作成し,その拡張子を手入力で “.rst” に書き換えるだけで良い.
 軽量マークアップ言語(=マークダウン言語)とは,プレーンなテキストから.htmlファイルを生成することを目的に作られた言語であり,記述方法のことである.そのため,ファイルのデータ構造そのものはプレーンなテキストファイルであり,拡張子を.txtから.rtsへ手入力で書き換えても支障が無い.

 本投稿では,ドキュメント生成する非コードのファイル名を “sampleMarkupLanguage.rst” とする.これには軽量マークアップ言語の記述例を記載し,筆者のGitHubアカウント[1]にて公開する.

 この第4章で扱うフォルダ/ファイルに関するディレクトリの概況は,下記の通りである.

Sphinx
├─ docs
│ ├─ build
│ └─ source
│   ├─ conf.py
│   ├─ index.rst
│   ├─ samplePython.rst
│   └─ sampleMarkupLanguage.rst
└─ samplePython.py

 index.rstの “toctree” に,ドキュメント生成したいファイル名を,拡張子.rstを除いた状態で加筆する(例:”sampleMarkupLanguage”).index.rstを編集した様子を,図5に示す.

.. toctree::
:maxdepth: 2
:caption: Contents:

samplePython
 sampleMarkupLanguage

図5 編集したindex.rstの様子

 仮想環境をactivateするコマンド例を以下に示す.

D:\Sphinx\Scripts\activate

 第4.1節で用意した.rstファイルは新たに用意したものであるため,Pythonモジュールから作成した.rtsファイルが既にある場合は,そのPythonモジュールの.rstファイルも更新する必要がある.
 理由は,Webサイト形式のドキュメント間における相互リンクを作成するためである.Pythonモジュールから作成した既存の.rstファイルは,第4.1節で新たに用意した.rstファイルが無かった状態で作成されたものであるため,Pythonモジュールから作成した既存の.htmlファイルには,第4.1節で新たに用意した.rstファイルに対するリンクが記述されていない.この更新をせずに各.rstファイルの.htmlファイルの作成だけすると,既存のPythonモジュールのドキュメント(Webページ)閲覧時は,Webページ内の左側にあるCONTENTS欄において,新たに第4.1節で用意した.rstファイルが掲載されていない不具合が生じる.

 更新する際は,Pythonモジュールから作成した既存の.rstファイルを一度削除し,改めて.rstを作成する.まずは下記コマンドにより,Pythonモジュール(cf. 第3章)が格納されたディレクトリへと移動する.

cd D:\Sphinx

 もしコマンドプロンプト上のカレントディレクトリがCドライブであり,Dドライブなど別ドライブに移動したい場合は,コマンド “cd” におけるドライブ移動のオプション “/d” を加える必要がある.

cd /d D:\Sphinx

 そして対象のPythonモジュールに対し,.pyファイルから.rstファイルを作成する..rstファイルの作成は,下記コマンドでできる.

sphinx-apidoc -f -o ./docs/source ./

 Pythonモジュールから作成した既存の.rstファイルを一度削除しなくとも,上記コマンドにより上書き保存され更新される場合もあるが,環境次第では上記コマンドだけでは更新されない場合もある.そのため,一度削除しておくと,更新が反映された新たな.rstファイルが確実に作成される.

 次の第4.5節では,.htmlファイルを作成する.それに向け,コマンドプロンプト上でのディレクトリを,下記コマンドで移動する.

cd D:\Sphinx\docs

 下記のコマンドを実行すると,ディレクトリ “D:\Sphinx\docs\build\html” に,第4.1節で用意した.rstファイルから作成した.htmlファイルが格納される.このhtmlフォルダ内にあるindexファイルが,いわゆるホームページに該当する.

make html

 第4.1節で用意した.rstファイルに変更があった際は,下記に挙げる,これまで前述してきた内容を再び実行すれば,更新内容が反映されたドキュメントが新たに生成される.
 第4.4節で述べたPythonモジュールから作成した既存.rstファイルの更新においては,第4.1節で用意した.rstファイルが新規追加であった場合に必要な操作にすぎず,第4.1節で用意した.rstファイルの更新時には,第4.4節の操作は不要である.

  • 第4.3節:仮想環境のactivate
  • 第4.5節:sourceフォルダのディレクトリへ移動
  • 第4.6節:.htmlファイルの作成

5. Sphinxの設定や軽量マークアップ言語などの記述方法

 テーマをインストールし,conf.py上のテーマに関する記述を書き換えることで,外観を図6のように変更できる.

図6 テーマを変更した様子(左:初期テーマalabaster/右:sphinx_rtd_theme)

 テーマの変更方法に関し,第2.4節にて環境構築/インストールで記述したテーマのインストールが,既に済んでいることを前提に説明する.
 conf.pyにおけるhtml_themeに関する記述に対し,下記の通り変更する.

# html_theme = "alabaster" # Webサイト形式のドキュメントにおける,デフォルトのテーマ
html_theme = "sphinx_rtd_theme" # Tips 第1章でインストールしたテーマ

 Webサイト形式のドキュメントであるため,CSSの使用が可能である.この第5.2節で説明する内容を実行すると,図7のように外観を変更できる.

図7 CSSw適用した様子(左:適用前/右:適用後)

 まず使用したい.cssファイルを用意する.本投稿では,見出し(H1~H3)に対する文字の色や装飾に関する記述をしたsampleCSS.cssを例示する.sampleCSS.cssの記述内容は下記の通りである.

h1{
	color: #2980B9; /* 文字の色 */
	padding: 0em 0em; /* 上下の余白 */
	border-top: solid 5px #2980B9; /* 上線 */
	border-bottom: solid 5px #2980B9; /* 下線 */
}

h2{
	color: #494949; /* 文字の色 */
	padding: 0.4em 0.5em; /* 文字の上下 左右の余白 */
	background: #f4f4f4; /* 背景色 */
	border-left: solid 5px #2980B9; /*左線 */
	border-bottom: solid 5px #d7d7d7; /* 下線 */
}

h3{
	border-bottom: solid 3px #2980B9; /* 線の種類(実線) 太さ 色 */
}

 用意した.cssファイルを,下記のように “_static” フォルダに格納する.

Sphinx
└─ docs
  ├─ build
  └─ source
    ├─ conf.py
    │ └─ _static 
    └─ index.rst

 次に,conf.pyに “html_css_files” の記述を下記の通り加筆する.

html_css_files = ["header.css"] # CSSの適用(複数のCSSファイルを適用する場合は,カンマ区切りで可能)

 最後に,コマンドプロンプトにて下記コマンドを入力し,ディレクトリの移動と.htmlファイルの再出力を行い,変更を反映させる.

cd D:\Sphinx\docs
make html

 .htmlファイルの作成方法において,第3.8節や第4.6節で紹介したコマンド “make html” 以外にも,以下に示すコマンドで作成することが可能である.そして,以下に示すコマンド中のパスは,コマンドプロンプト上でのカレントディレクトリが, 下記のディレクトリ概況における “D:\Sphinx” の場合を前提とした例である.

D:\Sphinx
└─ docs
  ├─ build
  ├─ _build
  └─ source
    ├─ conf.py 
    └─ index.rst
sphinx-build ./docs/source ./docs/_build/

上記コマンドにおいて,前半のディレクトリ(”./docs/source”)は,conf.pyが格納されているディレクトリを意味する.
 後半のディレクトリ(”./docs/_build/”)は,.htmlファイルを作成し格納するディレクトリを意味する.ただしコマンドmake htmlの場合と異なり上記コマンドの場合は,フォルダ_buid以下にて,フォルダdoctreesとフォルダhtmlとでの,各ファイルのフォルダ分けがされない.

 画像や動画の挿入方法として,軽量マークアップ言語による “image” と”figure” の2通りがある.image(写真や図)と異なり,figure(図)は,図としてキャプションの指定などのオプションがある.
 ”image” や “figure” による挿入は,挿入先の.rstファイルがあるディレクトリを起点として,対象画像や動画のパスを指定する.本投稿では各ドキュメントの.rstファイルを下記ディレクトリ概況におけるsourceフォルダに格納している.そこで例として,sourceフォルダ以下にimagesフォルダを作成し,各図や動画を格納した場合で,”image” や “figure” による記述を例示する.

D:\Sphinx
└─ docs
  ├─ build
  ├─ _build
  └─ source
    ├─ images
    │ ├─ 画像の挿入例.jpg
    │ └─ 動画の挿入例.mp4
    ├─ conf.py 
    ├─ index.rst
    ├─ samplePython.rst
    └─ sampleMarkupLanguage.rst

 imageによる記述例を以下に示す.

.. image:: ./images/図の挿入例.jpg

 figureによる記述例を以下に示す.

.. figure:: ./images/図の挿入例.jpg
	:width: 100%
	:align: center
	:alt: 図 figureを用いて図を挿入した様子
	
	図 figureを用いて図を挿入した様子

 figureは,下記のオプションを指定することができる.

  • width:Webページの表示領域に対する横幅の割合
  • align:画像やキャプションの配置.center(中央揃え)の他,left(左揃え)や,right(右揃え)の入力値が可能
  • alt:画像や動画ファイルを読み込めなかった場合に表示する文字列
  • キャプション:前述までのオプションに対し,空行を1行挟んだ上で指定する

 このfigureの記述は,.rstファイルに手書きした非コードのドキュメントだけでなく,Pythonコード中にコメントとしての記述も可能である.図8は,Pythonコード中のクラスsampleClassの概要部分におけるコメント文に,figureの記述を施した場合の例である.

図8 Pythonコード中にfigureで図を挿入したい場合の記述例

 動画を挿入する場合について説明する.
 ”figure” を用いることで,動画ファイルの挿入とブラウザ上での再生が可能である.動画の対応形式として,少なくとも.mp4ファイルであれば可能であることを,筆者は確認している.動画は,常に再生され続けているのではなく,挿入した動画をクリックすると,ブラウザ上で動画ファイルにアクセスする形で再生される(図8).つまりSphinxが行っているのはあくまでWebページへのリンクの挿入であり,動画の再生自体はブラウザの機能だと思われる.そのため,使用ブラウザが対応しているフォーマットであれば,.mp4ファイル以外でも再生可能だと思われる.
 オプションaltを設定しておくと,画像ファイルの場合とは異なり,動画ファイルを正常に読み込めている場合でも,まるでキャプションのように動画の下部に常に表示される(図8).

図9 挿入した動画の挙動

6. トラブルシューティング

 コマンドmake html実行時に,警告文「modules.rst: WARNING: document isn’t included in any toctree」が表示される.この警告内容は「どこからも参照されていない.rstファイルがある」という内容であるため,無視しても問題はないと思われる.また,この警告文は参照されていないファイルが実際は無くとも出る模様である.

 Pythonモジュールのimport文において,”import as” や “from import”の記法を用いていると,Sphinxで.htmlファイルを生成する際に下記のような警告が出る(図10).

WARNING: autodoc: failed to import module '(該当Pythonモジュール名)'; the following exception was raised:
No module named '(該当ライブラリ名)'

 上記の警告文は,警告でありながらPythonモジュール内に記述したコメントの一切がドキュメントに反映されなくなるため,実質エラーに等しい.
 原因は,import記法によってモジュールやオブジェクトが特定できず,Sphinxでの処理において未宣言扱いになるためである.
 解決方法は,conf.pyに “autodoc_mock_import” の記述を追加することで,この警告を回避できる.これは,任意のimportライブラリをモックとして扱う記述であり,モックとして扱うことで件の警告を回避できる.図11は,図10を例とした場合の記述例である.

図10 Pythonモジュールのimportにおける警告が出る記述例
図11 import関連のエラー回避に向けたconf.pyの記述例

 ただし,”from import” つまりは “from ライブラリ名 import 関数名” などの記法において,さらに “from ライブラリ名 import *” のように “*” (ワイルドカード)を用いた記述をしている場合,前述とはまた別の警告(エラー)を起こす.そのため,ワイルドカードを用いたimporの記法を,そもそも避けでコーディングした方が良い.ワイルドカードを用いた記法は,PEP8においても非推奨とされている.
 具体例として,図10におけるワイルドカードを用いた記法に対し,ワイルドカードを用いない記法へ書き換えた場合を以下に示す.ワイルドカードを用いないため,importし用いたい関数等を全て列挙する必要がある.

# from pycaret.regression import # ワイルドカードを用いた非推奨の記法.SPhinxにおいては警告(エラー)を引き起こす
from pycaret.regression import setup, compare_models, create_model, tune_model, finalize_model, save_model, plot_model, predict_model # ワイルドカードを用いずに用いる関数等を全て列挙する記法

参考文献

  1. YANAKA Shunsuke, ynksnk/makeDocumentsBySphinx, GitHub, https://github.com/ynksnk/makeDocumentsBySphinx, (参照2025-1-21).
  2. Pythonのインストールと仮想環境の構築方法~コマンドプロンプト~ – word in the world, word in the world, https://word-in-the-world.com/2025/01/02/python-virtualenvironment-01/,(参照2025-1-2).