Sphinxの使用方法を学ぶ

はじめに

UNVTで使用しているデプロイメントガイドというドキュメントがSphinxで記載されており、そのドキュメントの改訂のためSphinxの使用方法を学びました。その内容をまとめておきます。

環境

macOS Sequoia 15.3.2（チップ：Apple M3)
Python 3.13.2
pip 25.0

Sphinxのインストールと初期化

HomebrewがPythonのグローバル環境へのpip installを制限しているらしく、仮想環境にインストールする必要があります。

venv という名前の仮想環境ディレクトリを作成します。

python3 -m venv venv

仮想環境の有効化（アクティベート）

source venv/bin/activate

有効化されると、プロンプトが (venv) のように変化し、以後の python や pip の操作はこの仮想環境内に限定されます。

Sphinx をインストール

pip install sphinx

Sphinx プロジェクトの初期化

sphinx-quickstart

ソースと、ビルド結果のフォルダを分けるか聞かれるので、とりあえず分けました。
あとは適当に回答します。

仮想環境の終了

deactivate

グローバル環境に Sphinx が入っていないので、仮想環境の有効化をしてから作業し、仮想環境の終了をする必要があります。今後の作業の流れイメージは以下です。

source venv/bin/activate
make html
deactivate

HTMLファイルをビルドする

make html

source/ ディレクトリ内の .rst ファイルをもとに build/html/ に HTML ファイルを出力します

ビルド後にHTMLを開くには以下を実行します。

open build/html/index.html

とりあえず、見られました。

デザインテーマの変更

デザインテーマの変更を行います。
source/conf.py
のhtml_themeの値を変更します。

デプロイメントガイドが、こちらのサイトの「bizstyle」を使用しているので、それに変更します。以下のとおりデザインテーマが変更されました。

拡張機能の追加

source/conf.py
の
extensions = []
に追記します。

extensionsとは、Sphinx で使う拡張機能（extensions）をリストで指定する設定項目で、conf.py に書くことで、Sphinx のビルド時に自動でその機能が有効になります。

extensions = [
    'sphinx.ext.duration',
]

ビルド時間を測定する拡張機能です。sphinx-build 実行時に、各ステップにどれだけ時間がかかったかを表示してくれます。

topページに目次を作成する

次に TOP ページである index.rst に追加して、目次を作成します。

# index.rst
Welcome to test_document's documentation!
=========================================

.. toctree::
   :maxdepth: 2
   :numbered:
   :glob:

   chapter1/index
   chapter2/index
   chapter3/index

Search
==================
* :ref:`search`

.. toctree::
Sphinxで使う目次ディレクティブです。
これ以降に書かれたファイルがサブページ（リンクとして自動的に組み込まれます。

maxdepth : 目次に表示するのツリーの深さを指定
numbered : セクションに自動で番号をつける
glob : ワイルドカード（*）が使える。たとえば、chapter*/index のように書けば chapter1/index chapter2/index chapter3/index などを一括指定可能

• :ref:search : ページ内に「Search」という見出しができます。

PDFを出力する

PDFとしてドキュメントを出力する方法をまとめます。

MacTeXのインストール

必要なパッケージであるMacTeXのインストールを行います。
Homebrewでインストールします、15分程度かかりました。

brew install --cask mactex

パスを通して、設定を反映します。

echo 'export PATH="/Library/TeX/texbin:$PATH"' >> ~/.zshrc
source ~/.zshrc

LaTeX対応の設定をSphinxに追加します。
以下を conf.py の末尾に追記します。

conf.py

# -- Options for LaTeX output (PDF) ------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output

latex_engine = 'pdflatex'  # You can also use 'xelatex' if custom fonts or Unicode are needed

latex_elements = {
    'papersize': 'letterpaper',  # US Letter size (8.5 x 11 inches)
    'pointsize': '11pt',         # Base font size
    # Optional preamble customization
    'preamble': r'''
% Add any custom LaTeX packages or formatting here
''',
}

source venv/bin/activate
としてから、LaTeXファイルの生成とPDF出力を実施します。

make latexpdf

作成されたPDFファイルは、
build/latex/
に保存されます。あります。

まとめ

Sphinxの使用方法を簡単にまとめました。

Reference