【書評】 Sphinxをはじめよう 第3版

はじめに

設計書、手順書、議事録、APIリファレンス。エンジニアはコードと同じくらいドキュメントを書いています。
ところが、ドキュメントの「構造」や「管理」にはコードほど気を配れていない現場も多いのではないでしょうか。

今回読んだのは、オライリー・ジャパンの『Sphinxをはじめよう 第3版』です。

項目	内容
書名	Sphinxをはじめよう 第3版
著者	清水川 貴之、小宮 健、山田 剛、若山 史郎
出版社	オライリー・ジャパン
対象バージョン	Sphinx 4.3.1 / Python 3.10 以降

結論から言うと、本書は「ツールの使い方」の本であると同時に、ドキュメントを構造化して、ソースとして管理するという考え方の入門書でもありました。
本記事では、設計・アーキテクチャに関心のあるエンジニアの視点で、本書の内容と学びをまとめます。

この本の一言まとめ

• 1つのテキスト原稿から、HTML・PDF・EPUBを生成する方法を、手を動かしながら学べる
• 題材は議事録、インストール手順書、技術書と身近で、章ごとに完結している
• 応用(運用ノウハウなど)はあえて省き、基礎に絞っている
• Pythonやプログラミングの知識は不要。必要なのはテキストエディタの使い方だけ

全体構成

章	タイトル	主な内容
1	Sphinxとは	用途、用語、reSTの思想、他ツールとの比較
2	Sphinxのインストール	Windows / macOS / Linux それぞれの手順
3	HTMLに変換してみよう	プロジェクト作成、reST基礎、HTMLテーマ
4	PDFに変換してみよう	表、ディレクティブ、コードブロック、toctree
5	EPUBに変換してみよう	図、ラベルと参照、EPUB向け設定
6	画像の変換と埋め込み	figureの詳細、画像形式の切り替え、作図サービス連携
付録	リファレンスほか	reSTリファレンス、出力形式一覧、TeX Live、Markdownで書く方法、コミュニティ

構成がよく考えられていて、章を追うごとに「書く」「分割する」「参照する」「見栄えを整える」と段階的に機能が増えていきます。

第1章: Sphinxとは何か

生まれた背景

Sphinxは、もともとPython公式ドキュメントを作るために生まれたツールです。
当時のドキュメントは組版システムのLaTeXで書かれており、高品質ではあるものの、更新に踏み出すハードルが高かったそうです。
そこで「もっと更新しやすく、使いやすいツールを」という動機で、軽量マークアップ言語のreStructuredText(以下reST)を採用して作られました。

変換の流れ

Sphinxの基本構造はシンプルです。

原稿はあくまでテキストファイルで、設定は conf.py、成果物はビルドで生成します。
この「ソース」と「成果物」の分離は、ソフトウェア開発のソースコードとバイナリの関係にそのまま重なります。

他のツールとの比較が参考になる

本書は、よく比較されるツールとの違いを丁寧に整理しています。

• Officeスイート: 全体のスタイルが必ず統一される点、バージョン管理(Gitなど)と相性が良い点が強み。一方で、部分的な見た目の調整は苦手です
• Wiki: ページ単位で、どこから読んでもよい構造に向く。Sphinxは頭から最後まで読み進めるタイプの文書に向く、という整理が分かりやすいです
• Markdown + Jekyll: Markdownは記法が少なく拡張を前提としていないため、派生仕様が多数あります。reSTは拡張可能な設計です

どれが優れているという話ではなく、「文書の性質に合うツールを選ぶ」という姿勢が一貫しているのが好印象でした。
Sphinxが向かない分野(細かいレイアウト指定や、計算結果を出力する用途)にも正直に触れています。

構造化は設計の話でもある

本書では、箇条書きの議事録を「reSTで書いた場合」と「独自記法で書いた場合」で比較しています。
短い文書なら差は小さいものの、文書が大きくなるほど差が開くという指摘は、コードの可読性とまったく同じ話だと感じました。

reSTは、見出しの装飾記号の登場順で階層レベルが決まる仕組みです。
ただし本書では、混乱を避けるために記号の優先順位を統一することを勧めています。
チーム内のコーディング規約に近い発想です。

第2〜3章: 環境構築と最初のHTML

インストール

第2章は、OSごとの環境構築です。Windows、macOS、Linuxのそれぞれについて、Pythonのインストールから sphinx-quickstart --version での確認まで、画面イメージ付きで説明されています。
pip install ベースで進むため、Python経験者には馴染みのある流れです。

Linuxの節では、Sphinxが要求するPythonのバージョンと、古いディストリビューションとの関係にも触れられています。
実務で古い環境に当たったときに役立つ注意点です。

プロジェクトの作成とビルド

第3章では、対話形式の sphinx-quickstart でプロジェクトのひな形を作り、make html でビルドします。
生成されるファイルと役割は次の通りです。

ファイル	役割
conf.py	ビルド設定ファイル(Pythonスクリプト)
index.rst	原稿のひな形
Makefile / make.bat	ビルドスクリプト
_build/	成果物の出力先
_static/	静的ファイルの置き場
_templates/	HTMLテンプレート用

Sphinxは更新されたファイルだけを検知して差分ビルドします。
そのため、大きなドキュメントでも2回目以降は速く、これはビルドシステムとして素直で納得感のある設計です。

reST記法の基礎を、議事録で学ぶ

本書の上手いところは、議事録という身近な題材に記法を1つずつ当てはめていく点です。
「議事録の要素」と「対応する記法」が表で整理されているので、記法を目的から逆引きできます。

• 会議名・議題 → セクション(見出し)
• 参加者・日時 → リスト
• 会議の目的 → 段落、引用ブロック
• 状況の報告 → リスト、サブリスト
• 決定事項 → インライン記法(強調など)
• 外部資料 → ハイパーリンク
• 検討中のメモ → コメント

つまずきやすい点が先回りして書かれている

初学者がハマりやすいポイントを、図付きで解説しているのも本書の特長です。

• 改行は単なる折り返しで、空行で区切られたまとまりが段落になる
• サブリストの前には空行が必要で、インデントの桁数によって解釈が変わる
• 番号付きリストは、番号の桁数によってインデントの基準位置が変わる
• インライン記法の前後には半角スペースか改行が必要で、全角スペースは使えない
• バックスラッシュのエスケープと、macOSでの円記号との取り違え

reSTは「インデントと空行が意味を持つ」言語です。
PythonやYAMLに慣れている方なら、感覚はつかみやすいと思います。

ハイパーリンクの2方式

リンクの書き方には、文中にURLを埋め込む方式と、リンク先を別に定義して参照する方式があります。
後者は本文の可読性を保てるため、リンクが多い文書で効果的です。
これは「定義と利用の分離」という、設計でおなじみの考え方そのものです。

HTMLテーマの切り替え

conf.py の html_theme を書き換えるだけで、見た目が切り替わります。
内容は一切変えずに見た目だけ差し替えられるのは、関心の分離の分かりやすい実例です。

第4章: PDF変換と、文書の構造化

TeX経由の二段階変換

SphinxはPDFを作るとき、一度TeX形式に変換してからPDFにします。
利用者がTeXを書く必要はありませんが、TeX Live(macOSならMacTeX)の導入が必要です。
環境構築の手間はあるものの、一度整えれば make latexpdf の1コマンドで済みます。

ディレクティブという拡張ポイント

この章で登場する ディレクティブ は、reSTの拡張の仕組みです。
たとえば表を書く list-table、注意書きの note、コードを色付けする code-block などがあります。

表の記法は複数紹介されており、それぞれの得失が整理されています。

記法	特徴
Simple Table	手軽だが、罫線の長さ調整が必要
Grid Table	結合セルや複数行に強いが、保守しにくい
list-table	内容が変わっても壊れにくいが、表として見えにくい
csv-table	既存のCSVデータを流用しやすい
Field List	見出しと値のペア向け

「読みやすさ」と「書き換えやすさ」のトレードオフを、記法ごとに説明してくれているのが実務的です。

toctree: 文書を木構造で捉える

この章の核心は toctree ディレクティブだと感じました。
toctree は、ToC(目次)の木を意味する造語で、文書を複数ファイルに分割しつつ、全体の木構造を表現する仕組みです。

.. toctree::

   purpose
   procedure/index
   verification

ポイントは次の通りです。

• HTMLでは目次(リンク集)になり、PDFでは各ファイルの内容が取り込まれる
• 各ファイルにはセクション見出しが必要。ないと警告が出る
• どの toctree にも含まれていないファイルも警告の対象になる
• 章立ての変更は、toctree 内の順序を入れ替えるだけで済む

設計の観点では、toctree はドキュメントのモジュール構成そのものです。
大きな文書ほど「最初に大まかな構成を決め、章ごとにファイルを用意してから書く」という進め方が効く、という著者の実体験に基づく助言は説得力がありました。

PDF変換では、原稿の最初のセクション名は出力されません。
表紙のタイトルは、conf.py の project の値が使われます。
HTMLとの挙動の差なので、初見だと戸惑うポイントです。

第5章: EPUBと、参照の仕組み

ラベルと参照

技術書では「3章で述べたように」「図4.1のとおり」といった相互参照が欠かせません。
Sphinxでは、ラベルで場所に名前を付け、refでそのラベルを参照します。

.. _beginning:

はじまり
========

:ref:`beginning` を参照します。

• ラベルはプロジェクト全体で重複できない(重複するとビルド時に警告)
• 参照先がセクションや図なら、タイトルやキャプションが自動でリンク名になる
• 図表番号で参照したい場合は、numfig を有効にして numref を使う

名前を付けて参照する、という点では、識別子とシンボル参照の関係に近いと言えます。
リンク切れをビルド時の警告で検知できるのも、ドキュメントを「コンパイルする」感覚に近く、品質管理に使えます。

EPUBの出力設定

make epub で電子書籍形式を出力できます。
表紙(サムネイル画像と扉ページ)や、タイトル、著者、出版社、識別子などのメタデータは conf.py で設定します。

実用的なヒントとして、次の3点が挙げられています。

1. 1つの章を長くしない(リーダーによっては読み込みが遅くなる)
2. 文書構造を深くしすぎない(epub_tocdepth で目次の深さを制限できる)
3. 記法による装飾を減らす

第6章: 画像の扱い

第6章では、画像を作るところから埋め込むところまでを扱います。

figureディレクティブ

画像の埋め込みの基本は figure ディレクティブです。
引数には、相対パス、プロジェクトルートからの絶対パス、URLのいずれかを指定でき、配置、代替テキスト、サイズ、リンクなどのオプションがあります。

出力形式ごとに画像を出し分ける

出力形式によって扱える画像形式が違います。
たとえばSVGはHTMLやEPUBでは使えますが、PDF(LaTeX)では使えません。

Sphinxには、ファイル名の拡張子を .* と書いておくと、ビルド時に出力形式に適した画像を選んでくれる仕組みがあります。
PNGとSVGの両方を置いておけば、HTMLではSVG、PDFではPNGが使われます。

.. figure:: images/logo.*

   ロゴ

さらに、標準添付の拡張 sphinx.ext.imgconverter を使うと、ImageMagickを利用して画像形式を自動変換できます。
ただし、ベクター形式から変換すると画質が落ちることがあるため、高品質にこだわるなら出力形式ごとの画像を用意するのがよい、という注意書きも添えられています。

作図サービスとの連携

本書は作図に外部のオンライン作図サービスを使っており、そのサービスと組み合わせて図を管理する方法も紹介しています。
「原稿はテキスト、図は別ツールで作ってファイルとして取り込む」という分業は、Sphinxの思想に沿ったやり方です。

付録の充実度

付録には、次の内容がまとまっています。

• reStructuredTextのリファレンス
• Sphinxが使える出力形式
• TeX Live / MacTeXのインストール
• Markdownで書いてみよう
• Sphinxのコミュニティ

Markdownの付録は、Markdown派のチームでSphinxを使いたい場合に有用です。
第3版では、Markdown変換に使う拡張が recommonmark から MyST-Parser に変更されています。

第3版での主な変更点

項目	内容
対応バージョン	Sphinx 4.3.1 に更新
Markdown拡張	recommonmark から MyST-Parser へ変更
付録の整理	不要になった付録(質問一覧、Windows向けのmake/shの導入)を削除

本書は2021年11月リリースのSphinx 4.3.1を前提に書かれています。
それ以降のバージョンでは、画面や出力、設定項目に差が出る可能性があります。
読み進める際は、公式ドキュメントも併せて確認することをおすすめします。

良かった点

1. 題材が実務に近い: 議事録、インストール手順書、技術書と、手を動かす対象が分かりやすいです
2. 段階的に学べる: 各章の「まとめ」で、新しく覚えた記法が一覧になります
3. つまずきの先回り: 空行、インデント、全角スペースなど、実際にハマる箇所に図付きで触れています
4. ツールの限界も書いてある: 向かない分野を明記しており、選定の判断材料になります
5. 設計の考え方が学べる: 構造化、関心の分離、分割と参照といった発想が自然に身につきます

気になった点・注意点

1. 応用は範囲外: 運用方法(CI連携や継続的な公開など)は、意図的に省かれています。その先はコミュニティの情報に頼ることになります
2. reST特有のクセ: インデントと空行の規則は、慣れるまで警告との付き合いが続きます
3. PDFは環境構築が重め: TeX環境の準備に手間がかかります
4. バージョンの時間差: 前述の通り、記述は4.3.1時点です

こんな人におすすめ

• Sphinxを初めて触る人
• 設計書や手順書を、Gitで管理できる形式にしたい人
• コードサンプルを含む技術ドキュメントを作りたい人
• HTML、PDF、EPUBを1つの原稿から出力したい人
• ドキュメントの構造化について、実践的に学びたい人

逆に、すでにSphinxで拡張やCI運用まで行っている人には、基礎の確認が中心になると思います。
その場合は付録のリファレンスが手元の辞書として使えます。

学びのまとめ

本書から持ち帰った考え方を、設計の言葉でまとめます。

Sphinxの機能	設計上の考え方
原稿(reST)と成果物の分離	ソースと成果物の分離
conf.py とHTMLテーマ	設定と内容の分離、関心の分離
toctree	モジュール分割と依存構造の明示
ラベルと ref	名前による参照、リンク切れの機械的検出
ディレクティブ	拡張ポイント
差分ビルド	変更検知によるビルド効率化

ドキュメントも、コードと同じように「構造」「分割」「参照」「ビルド」で捉えると、保守しやすくなります。
Sphinxはそれを実現するための、手触りの良い入口でした。

おわりに

『Sphinxをはじめよう 第3版』は、ドキュメント作成の苦手意識を減らしつつ、ドキュメントをソースとして扱う感覚を教えてくれる一冊でした。
議事録1つでも、reSTで書いておけば後から資産として活きてきます。

まずは身近なメモを .rst で書いて、make html で変換するところから始めてみてはいかがでしょうか。

参考

• 『Sphinxをはじめよう 第3版』(清水川貴之、小宮健、山田剛、若山史郎 著、オライリー・ジャパン刊)
• 書籍ページ(オライリー・ジャパン)
• Sphinx 公式ドキュメント(日本語)
• sphinx-users.jp