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
```

とりあえず、見られました。
![スクリーンショット 2025-04-04 14.04.05.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3684675/61439383-48b5-42b0-8d02-03b54158bcdd.jpeg)


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

デプロイメントガイドが、[こちらのサイト](https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes)の「bizstyle」を使用しているので、それに変更します。以下のとおりデザインテーマが変更されました。

![スクリーンショット 2025-04-04 14.03.19.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3684675/25a22c90-c802-44e8-8a96-68225fcde915.jpeg)

# 拡張機能の追加
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 の末尾に追記します。

```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
https://qiita.com/T-ubu/items/1bf7514ec43a3d1c6eb4

https://qiita.com/kinpira/items/505bccacb2fba89c0ff0

https://www.sphinx-doc.org/en/master/

https://sphinx-users.jp/