Python製のドキュメント生成ツール。
- Python 3.8.5
- Sphinx 3.4.2
pip3 install Sphinx
reST（reStructuredText）
SphinxではデフォルトでreStructuredTextというマークアップ言語を使う。
- https://www.sphinx-doc.org/ja/master/usage/restructuredtext/basics.html
- https://atom.io/packages/language-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への自動デプロイを整備する。