Sphinx

Tue, 05 Jan 2021 07:40:00 +0900

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

Python 3.8.5
Sphinx 3.4.2
- Sphinx · PyPI

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スタイルのドキュメントを生成できる。

ドキュメント on えやみぐさ

Sphinx

reST（reStructuredText）

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