Sphinx

Python製のドキュメント生成ツール。

pip3 install Sphinx

reST(reStructuredText)

SphinxではデフォルトでreStructuredTextというマークアップ言語を使う。

既存Pythonプロジェクトにドキュメントを追加する

setup.py などが存在するPyPIパッケージプロジェクトを想定する。

プロジェクトのルートに docs ディレクトリを作成し、 インタラクティブツール sphinx-quickstart を実行する。

mkdir docs
cd docs/
sphinx-quickstart

Separate source and build directories (y/n) と聞かれるので、 y 。 プロジェクト名、著者名、言語などを答える。

source ディレクトリ、 build ディレクトリ、 Makefile が生成される。

make html

以上のコマンドで build/html ディレクトリにHTMLが生成される。

python3 -m http.server -b localhost -d build/html

などで確認する。

次はPythonモジュールのdocstringからドキュメントを自動生成する。

#!/bin/bash
SCRIPT_DIR=$(cd $(dirname $0); pwd)
cd "${SCRIPT_DIR}"
sphinx-apidoc -f -o "./source/api" "../mymodule"
make html

docs/mkdocs.sh を以上のように作成し、実行する(TODO:Makefileへの入れ込み)。 ここでは、以下のように docs ディレクトリと並んで、パッケージとして提供するPythonモジュール mymodule のディレクトリがあることを想定している。 なお、 docs/source/conf.py は設定ファイルであり、 例えば html_theme = 'sphinx_rtd_theme' のような設定を追加し、 pip3 install sphinx-rtd-theme してから make html することで、Read the Docsスタイルのドキュメントを生成できる。

|- setup.py
|
|- docs/
|- Makefile
|- mkdocs.sh
|
|- source/
|- conf.py
|- index.rst
|
|- build/
|- html/
|- index.html
|
|- mymodule/
|- __init__.py
|- mymodule.py

sphinx-apidoc によりPythonモジュールのドキュメントが source/api に自動生成され、 見出しにあたるページが source/api/modules.rst に生成される。 このページへのリンクがどこにもない、という旨のエラーが表示されているはずなので、 インデックスページの source/index.rst にこのページへのリンクを追加する。

.. toctree::
:maxdepth: 2
:caption: Contents:
api/modules

CI,CDを整備する

自動生成されるHTMLをソースコードと同じブランチでGit管理したくはないので、 docs/build ディレクトリを .gitignore に追加し、 GitHub ActionsやGitLab CIを使ってドキュメントの生成、GitHub PagesやGitLab Pagesへの自動デプロイを整備する。

Docker化・GitHub Actions整備の例