Sphinx は、Python で記述されているドキュメンテーションジェネレータで、reStructuredText (reST) を HTML や PDF 、EPUB 、Texinfo 及び man ページ などのフォーマットに変換します。reStructuredText には拡張性があり、Sphinx は拡張機能を通して、ソースコード からドキュメントを自動生成したり、数学的な記法を書いたり、あるいはソースコードをハイライト したりすることができます。
Sphinx は、Python で作成したアプリのマニュアルを HTML 形式で作成する際に利用しています。ちょっとした数式も綺麗に整形してくれるので大変重宝しています。さらに、LaTeX 形式で出力して PDF 形式に変換することもできます。
従来、メイン PC の OS には Fedora Linux を利用していましたが、ちょっとした不具合があったため、このところは安定動作を重視して RHEL 9 をインストールして利用していました。しかし、残念なことに自分の力では LaTeX をうまく動かせませんでした。😭
Fedora Linux 41 のベータ版がリリースされたので、我慢できずにメイン PC の OS を Fedora Linux に戻してしまいました。Fedora Linux 41 では LaTeX を問題なく利用できたので、この機に Sphinx の使い方をまとめておこうと考えました。
今回は HTML の出力を確認しつつも、LaTeX → PDF に変換して出力できる環境を整備することにも焦点をあてます。
下記の OS 環境で動作確認をしています。
Fedora Linux Workstation
41 beta x86_64
Python
3.13.0rc2
Sphinx
8.0.2
TeX Live パッケージ群のインストール
Sphinx を使い始める前に、Fedora の TeX Live パッケージ群をインストールしておきます。最低限必要なパッケージが何かを抽出できなかったので、乱暴なやり方ですが texlive で始まるパッケージおよび依存しているパッケージをすべてインストールしました。
bitwalk@fedora:~$ sudo dnf install texlive*
TeX Live に依存するパッケージを含め、7000 以上の膨大な数のパッケージ（texlive で始まるパッケージ数は 6763）がインストールされますが、個々のパッケージサイズはそれほど大きくないので、いまどきのストレージ容量であれば問題ないでしょう。
仮想環境 venv に Sphinx をインストール
ここではプロジェクトディレクトリ内に Python の venv 仮想環境を用意して Sphinx を pip コマンドでインストールしています。
bitwalk@fedora:~/MyProjects$ mkdir sphinx_sample
bitwalk@fedora:~/MyProjects$ cd sphinx_sample
bitwalk@fedora:~/MyProjects/sphinx_sample$ python -m venv venv
bitwalk@fedora:~/MyProjects/sphinx_sample$ source venv/bin/activate
(venv) bitwalk@fedora:~/MyProjects/sphinx_sample$ pip install sphinx
Collecting sphinx
Using cached sphinx-8.0.2-py3-none-any.whl.metadata (6.2 kB)
...
...
(venv) bitwalk@fedora:~/MyProjects/sphinx_sample$
クイック・スタート
プロジェクトのルート・ディレクトリで、sphinx-quickstart を引数を何も指定せずに実行します。docs のようなサブディレクトリ名を指定するのが一般的ですが、今回は文書作成専用のプロジェクトであるため、何も指定しませんでした。
下記のように質問に答えて、文書作成に必要となる基本的なディレクトリおよびファイルを生成します。
(venv) bitwalk@fedora:~/MyProjects/sphinx_sample$ sphinx-quickstart
Sphinx 8.0.2 クイックスタートユーティリティへようこそ。
以下の設定値を入力してください（Enter キーのみ押した場合、
かっこで囲まれた値をデフォルト値として受け入れます）。
選択されたルートパス: .
Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: Enter
プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。
> プロジェクト名: サンプル文書
> 著者名（複数可）: すぐりふひと
> プロジェクトのリリース []: 0.0.1
ドキュメントを英語以外の言語で書く場合は、
言語コードで言語を選択できます。Sphinx は生成したテキストをその言語に翻訳します。
サポートされているコードのリストについては、
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language を参照してください。
> プロジェクトの言語 [en]: ja
ファイル /home/bitwalk/MyProjects/sphinx_sample/conf.py を作成しています。
ファイル /home/bitwalk/MyProjects/sphinx_sample/index.rst を作成しています。
ファイル /home/bitwalk/MyProjects/sphinx_sample/Makefile を作成しています。
ファイル /home/bitwalk/MyProjects/sphinx_sample/make.bat を作成しています。
終了：初期ディレクトリ構造が作成されました。
マスターファイル /home/bitwalk/MyProjects/sphinx_sample/index.rst を作成して
他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。
make builder
"builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck。
(venv) bitwalk@fedora:~/MyProjects/sphinx_sample$
sphinx-quickstart で生成された、Sphinx による文書作成に関係があるディレクトリとファイルば下記になります。
bitwalk@fedora:~/MyProjects/sphinx_sample
┣ Makefile
┣ _build
┣ _templates
┣ index.rst
┣ _static
┣ conf.py
┗ make.bat
上記ファイルの内、conf.py ファイルは、Sphinx の入出力の動作をカスタマイズするために必要なほとんどすべての設定をおこなえるそうです。今回 sphinx-quickstart で生成した conf.py ファイルは、次のようになっています。
conf.py
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'サンプル文書'
copyright = '2024, すぐりふひと'
author = 'すぐりふひと'
release = '0.0.1'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = []
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
language = 'ja'
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'alabaster'
html_static_path = ['_static']
今回は。特にカスタマイズをせずに動作確認をしてみます。
空の文書をビルドしてみる
何も設定やファイルを追加していない状態で文書をビルドしてみます。
まずは HTML 形式で出力してみます。
(venv) bitwalk@fedora:~/MyProjects/sphinx_sample$ make html
Sphinx v8.0.2 を実行中
翻訳カタログをロードしています [ls]... 翻訳が用意されていません
出力先ディレクトリを作成しています... 完了
ビルド中 [mo]: 更新された 0 件のpoファイル
出力中...
...
（途中省略）
...
オブジェクト インベントリを出力... 完了
ビルド 成功, 17 警告.
HTMLページは_build/htmlにあります。
(venv) bitwalk@fedora:~/MyProjects/sphinx_sample$
_build/html/ 内に HTML が生成されます。index.html をブラウザで開くと下記のような、タイトルだけのページが表示されます。
~/MyProjects/sphinx_sample/_build/html/index.html (1)
次に、PDF 形式で出力してみます。
(venv) bitwalk@fedora:~/MyProjects/sphinx_sample$ make latexpdf
Sphinx v8.0.2 を実行中
翻訳カタログをロードしています [ja]... 完了
出力先ディレクトリを作成しています... 完了
保存された環境データを読み込み中... 完了
ビルド中 [mo]: 更新された 0 件のpoファイル
出力中...
...
（途中省略）
...
------------
Run number 1 of rule 'dvipdf'
------------
------------
Running 'dvipdfmx -o "sphinx.pdf" "sphinx.dvi"'
------------
sphinx.dvi -> sphinx.pdf
[1][2][3][4][5]
14139 bytes written
Latexmk: All targets (sphinx.dvi sphinx.pdf) are up-to-date
make[1]: ディレクトリ '/home/bitwalk/MyProjects/sphinx_sample/_build/latex' から出ます
(venv) bitwalk@fedora:~/MyProjects/sphinx_sample$
_build/latex/ 内に LaTeX の出力から PDF に変換された sphinx.pdf が出力されます。これをドキュメントビューアー で開くと HTML の時と同様にタイトルだけのページが表示されます。
~/MyProjects/sphinx_sample/_build/latex/sphinx.pdf (1)
空の文書とは言え、拡張モジュールとか追加しなくともとりあえずビルドできました。
文書を追加する
空の文書とは言え、Sphinx を利用して、HTML と PDF 形式の出力ができることを確認できたので、具体的に長い文書を追加してみます。
サンプル文書
題材とするサンプル文書は、青空文庫で公開されている「杜子春」にしました。
参考サイト [2] から 43015_ruby_17393.zip をダウンロードして解凍した toshishun.txt を開いて、新規ファイルに内容をコピーして、article_01.rst というファイル名でプロジェクトのルート・ディレクトリに保存しました。保存時のエンコードは UTF-8 です。
bitwalk@fedora:~/MyProjects/sphinx_sample
┣ Makefile
┣ _build
┣ _templates
┣ article_01.rst ← 「杜子春」の内容
┣ index.rst
┣ _static
┣ conf.py
┗ make.bat
.rst の拡張子が付いたファイルの内容は、reStructuredText (reST) の規則に従って記述されます。
今回は、article_01.rst にコピーした「杜子春」の内容に、文書のツリー構造を構成するために必須となる「セクション」を定義して、改行箇所を整えました。
article_01.rst の冒頭
杜子春
=========
芥川龍之介
一
--
或《ある》春の日暮です。
唐《とう》の都｜洛陽《らくよう》の西の門の下に、ぼんやり空を仰いでいる、一人の若者がありました。
若者は名を杜子春といって、元は金持の息子でしたが、今は財産を費《つか》い尽して、その日の暮しにも困る位、憐《あわれ》な身分になっているのです。
何しろその頃洛陽といえば、天下に並ぶもののない、繁昌《はんじょう》を極《きわ》めた都ですから、往来にはまだしっきりなく、人や車が通っていました。
門一ぱいに当っている、油のような夕日の光の中に、老人のかぶった紗《しゃ》の帽子や、土耳古《トルコ》の女の金の耳環《みみわ》や、白馬《しろうま》に飾った色糸の手綱《たづな》が、絶えず流れて行く容子《ようす》は、まるで画のような美しさです。
しかし杜子春は相変らず、門の壁に身を凭《もた》せて、ぼんやり空ばかり眺《なが》めていました。
空には、もう細い月が、うらうらと靡《なび》いた霞《かすみ》の中に、まるで爪の痕《あと》かと思う程、かすかに白く浮んでいるのです。
（以下、省略）
セクションは 6 レベルに分けられています。ここではレベル 2 で「杜子春」のタイトル、レベル 3 で章（一、二、三、…、六）を定義しました。詳しくは、参考サイト [3] をご覧になってください。
セクションの == などの文字数は、「杜子春」などのセクション名 の文字数以上でないと make コマンドでビルドするときに警告が出ます。UTF-8 の漢字１文字は 2 バイト固定ではなく、それ以上の場合もあります。（バイト数が同じでる必要があるような気がするので）多めにセクション文字を入れておいた方が良いでしょう。
reST で改行は空白行で表現するので、原文を改変してしまっていますが、勝手に改行を入れました。また先頭の全角空白の字下げは削除しました。
index.rst の編集
index.rst を編集して、文書のツリーに「杜子春」の article_01.rst を下記のように追加します。拡張子はつけません。インデントは上の :caption: と同じです。また :caption: から一行空けて記載します。
index.rst
.. サンプル文書 documentation master file, created by
sphinx-quickstart on Mon Sep 23 12:12:52 2024.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
サンプル文書 documentation
==========================
Add your content using ``reStructuredText`` syntax. See the
`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
documentation for details.
.. toctree::
:maxdepth: 2
:caption: Contents:
article_01
文書のビルド
空の文書をビルドしたときと同じように、HTML、PDF それぞれビルドします。
HTML は次のようになります。
~/MyProjects/sphinx_sample/_build/html/index.html (2)
「杜子春」をクリックすると表示が変わります。
~/MyProjects/sphinx_sample/_build/html/index.html (3)
PDF は次のようになりました。
~/MyProjects/sphinx_sample/_build/latex/sphinx.pdf (2)
~/MyProjects/sphinx_sample/_build/latex/sphinx.pdf (3)
PDF の出力では、空白ページが多かったり、セクション番号がついたりと、HTML 出力とは異なっています。必要に応じてカスタマイズする必要がありそうです。
一方、HTML の出力でも、今回はテーマの選択などのカスタマイズを全然していません。
これらは、十分確認した上で、本ブログでまとめていく予定です。
なお、本稿で使用したソースは下記で公開しています。
参考サイト
Sphinx — Sphinx documentation 図書カード：杜子春 4. Sphinxでの文章の書き方(reStructuredText) — study sphinx 1 documentation
VIDEO
にほんブログ村
#オープンソース
