Sphinx を用いたドキュメント構築

本ドキュメントの本文は Markdown 書式で記述され，Sphinx により HTML 出力がなされています．本ガイドでは，Windows11 上に Miniforge を用いた Python 仮想環境を構成し，Sphinx パッケージを導入しています．ドキュメント編集と HTML 出力は Visual Studio Code 上で行うことを想定しています．

動作環境

ホストOS ： Windows11 23H2

使用ソフトウェア： Miniforge3 24.9.2, Visual Studio Code 1.95.3

上記は 2024年11月時点のバージョンです．それぞれ適切な最新のバージョンを利用します．

Sphinx 動作環境の構築

Miniforge を導入して conda コマンドを用いた仮想環境の作成を行います．conda コマンドは環境作成・管理のみで利用し，パッケージの管理は pip を利用します．（例外として Python 本体や pip コマンドなどは conda により導入します）

Miniforge のインストールと仮想環境の作成

Miniforge の github レポジトリから最新の Miniforge3-Windows-x86_64 インストーラを取得し，これを実行します．なお，デフォルトではインストール先が隠しディレクトリに指定されているため，C:\Users(ユーザ名)\miniforge3 などへ変更します．

インストール後，スタートメニューから Miniforge Prompt を選択し，基本構成(base)を呼び出します．まず，conda 本体や基本パッケージのアップデートを行います．

conda update conda
conda update -all

次に，仮想環境（名称は env_doc とします）を作成し，仮想環境に移行します．

conda create -n env_doc python=3.12
conda activate env_doc

Sphinx のインストール

Sphinx 本体と書式やフォーマットなどのパッケージを導入します．

pip install -U sphinx
pip install myst_parser sphinx-rtd-theme sphinx_fontawesome sphinx_copybutton

Visual Studio Code との連携

Visual Studio Code のターミナルを Sphinx 環境とする連携設定を行います．（テスト用のフォルダを用意します．本ガイドでは，C:\User(ユーザ名)\Documents\sphinx_test とします．

Visual Studio Code を起動し，テスト用フォルダをオープンします．

次に，表示メニューからコマンドパレットを選択し，Python: Select interperter コマンドを入力し，Python インタプリタの選択を行います．選択では自動的に仮想環境 env_doc が検出されますので，これを選択します．

仮想環境が正しく選択されているか確認します．表示メニューのターミナルを選択し，Python や sphinx-* コマンドが有効であるか確認します．Python --version コマンドを実行すると，3.12.7 であることが確認できます．

Sphinx 動作確認

Python インタプリタの設定後，Visual Studio Code のターミナル上で sphinx-quickstart を実行します．実行時の設定を下記のように行います．

ソースディレクトリとビルドディレクトリを分ける： n
プロジェクト名：sphinx-test
著者名：test-user
プロジェクトのリリース：（空白）
プロジェクトの言語：ja

以上により，テスト文章のテンプレート一式が生成されます．

テンプレートには，生成を行う Makefile や rst (reStructedText) 型式の文章 index.rst，文章の構成を設定する conf.py など，各種フォーマットのドキュメントを生成するためのファイルが含まれています．

テンプレートから HTML 文章を生成します．ドキュメントは _build ディレクトリに格納されます．

make html

Markdown 型式利用，その他設定など

Sphinx インストール時に導入した拡張機能を利用し，Markdown 型式の利用や表示方法の変更を行います．

myst_parser：Markdown 型式が利用できるようになります
sphinx_rtd_theme：広く利用されているドキュメントのフォーマットが提供されます
sphinx_fontawesome：フォントの変更が可能となります
sphinx_copybutton：コードボックスにコピー機能を付与します

拡張機能を追加する設定を conf.py へ追加します．

extensions = [
    'myst_parser',
    'sphinx_rtd_theme',
    'sphinx_fontawesome',
    'sphinx_copybutton'
    ]

source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown'
}

ドキュメントの整形方法を変更します．

- html_theme = 'alabaster'
+ html_theme = 'sphinx_rtd_theme'