はじめに

Sphinxは、Pythonで開発された強力なドキュメント生成ツールです。
特に、技術文書やプロジェクトの設計書など、複数のファイルを統合して一つのドキュメントにまとめる際に非常に便利です。

本記事では、Sphinxを使って要件定義書、基本設計書、詳細設計書などを結合し、Mermaidを活用した図を含むドキュメントを生成する方法を詳しく解説します。
また、他の人にも公開できるようにPDF出力の方法やおすすめのHTMLテンプレートについてもご紹介します。

前提条件

Python がインストールされていること（バージョン3.6以上推奨）
基本的なコマンドライン操作の知識
テキストエディタ（Visual Studio Code、Atom、Sublime Textなど）

環境のセットアップ

Pythonのインストール確認

ターミナル（コマンドプロンプト）で以下のコマンドを実行し、Pythonがインストールされていることを確認します。
```
python --version
```
例：
```
Python 3.9.7
```
インストールされていない場合は、Python公式サイトからインストールしてください。
仮想環境の作成（推奨）

プロジェクトごとに依存関係を管理するために、仮想環境を作成します。
```
python -m venv sphinx_env
```
仮想環境をアクティブにします。
- Windows:
```
sphinx_env\Scripts\activate
```
- macOS/Linux:
```
source sphinx_env/bin/activate
```

Sphinxプロジェクトの初期化

Sphinxのインストール

仮想環境がアクティブな状態で、Sphinxをインストールします。
```
pip install sphinx
```
Sphinxプロジェクトの作成

プロジェクト用のディレクトリを作成し、そこに移動します。
```
mkdir my_documentation
cd my_documentation
```
Sphinxの初期化コマンドを実行します。
```
sphinx-quickstart
```
以下のプロンプトに従って設定します。一般的な設定例：
```
> Root path for the documentation [.]: .
> Separate source and build directories (y/n) [n]: y
> Project name: プロジェクト名
> Author name(s): 著者名
> Project release []: 1.0
> Project language [en]: ja
```
これにより、sourceとbuildディレクトリが作成されます。

Mermaidのサポートを追加

Mermaidは、テキストベースでダイアグラムを作成できる便利なツールです。
SphinxでMermaidを使用するために、sphinxcontrib-mermaid拡張機能を追加します。

必要なパッケージのインストール
```
pip install sphinxcontrib-mermaid
```

conf.pyの設定

source/conf.pyファイルを開き、以下の設定を追加または変更します。

# conf.py

# 拡張機能に'sphinxcontrib.mermaid'を追加
extensions = [
    'sphinxcontrib.mermaid',
    # 他の拡張機能があればここに追加
]

# Mermaidの設定（必要に応じて調整）
mermaid_version = "11.2.0"  # 使用するMermaidのバージョン

注意: mermaid_versionは最新の安定版に設定してください。公式ドキュメントで最新バージョンを確認できます。

ドキュメントの構造とファイルの準備

複数のドキュメント（要件定義書、基本設計書、詳細設計書など）をSphinxで管理し、1つの統合ドキュメントに結合します。

ディレクトリ構造の例

my_documentation/
├── build/
├── source/
│   ├── conf.py
│   ├── index.rst
│   ├── requirements.rst
│   ├── basic_design.rst
│   └── detailed_design.rst
└── Makefile

個別のドキュメントファイルの作成

各ドキュメント（requirements.rst、basic_design.rst、detailed_design.rst）をsourceディレクトリ内に作成します。

requirements.rst

Requirements
============

要件定義書の内容をここに記述します。

.. mermaid::

   graph TD
       A[開始] --> B{判断}
       B -->|はい| C[処理1]
       B -->|いいえ| D[処理2]
       C --> E[終了]
       D --> E

basic_design.rst

Basic Design
============

基本設計書の内容をここに記述します。

.. mermaid::

   sequenceDiagram
       participant User
       participant System
       User->>System: リクエスト送信
       System-->>User: レスポンス返却

detailed_design.rst

Detailed Design
===============

詳細設計書の内容をここに記述します。

.. mermaid::

   classDiagram
       class User {
           +String name
           +String email
           +login()
           +logout()
       }
       class Admin {
           +manageUsers()
       }
       User <|-- Admin

index.rstの編集

index.rstはドキュメントの目次となります。ここで各ファイルを参照します。

.. My Project documentation master file, created by
   sphinx-quickstart on Thu Apr 27 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to My Project's documentation!
======================================

.. toctree::
   :maxdepth: 2
   :caption: 目次

   requirements
   basic_design
   detailed_design

複数ファイルの結合設定

Sphinxのtoctreeディレクティブを使用して、複数のファイルを結合し1つのドキュメントにまとめます。
前述のindex.rstで既に設定済みです。

例: index.rst

.. My Project documentation master file, created by
   sphinx-quickstart on Thu Apr 27 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to My Project's documentation!
======================================

.. toctree::
   :maxdepth: 2
   :caption: 目次

   requirements
   basic_design
   detailed_design

これにより、requirements.rst、basic_design.rst、detailed_design.rstの内容が順番に統合されます。

HTMLテーマの選択と設定

Sphinxでは、様々なHTMLテーマを選択してドキュメントの見た目をカスタマイズできます。
ここでは、おすすめのHTMLテーマとして Furo、sphinx_rtd_theme、sphinx_material を紹介し、それぞれのインストール方法と設定方法を解説します。

1. Furo

Furo は、シンプルでモダンなデザインが特徴のテーマです。
レスポンシブデザインにも対応しており、デスクトップからモバイルまで幅広いデバイスで快適に閲覧できます。

インストール
```
pip install furo
```
設定

source/conf.py を開き、html_theme を 'furo' に設定します。
```
# conf.py

html_theme = 'furo'
```

2. Read the Docsテーマ (sphinx_rtd_theme)

sphinx_rtd_theme は、Read the Docsで使用されているテーマで、ドキュメントが見やすく整理されているのが特徴です。

インストール
```
pip install sphinx_rtd_theme
```
設定

source/conf.py を開き、html_theme を 'sphinx_rtd_theme' に設定します。
```
# conf.py

html_theme = 'sphinx_rtd_theme'
```

3. Sphinx Material

sphinx_material は、GoogleのMaterial Designに基づいた美しいテーマです。カスタマイズ性が高く、視覚的に魅力的なドキュメントを作成できます。

インストール
```
pip install sphinx-material
```
設定

source/conf.py を開き、html_theme を 'sphinx_material' に設定します。
```
# conf.py

html_theme = 'sphinx_material'

# オプション設定（例）
material_theme_color = 'blue'
material_logo = 'path/to/logo.png'
```
注意: sphinx_material は追加の設定オプションが豊富です。詳細は公式ドキュメントを参照してください。

ドキュメントのビルド

HTMLドキュメントのビルド

sourceディレクトリ内で以下のコマンドを実行します。

make html

成功すると、build/htmlディレクトリ内にHTML形式のドキュメントが生成されます。
ブラウザでindex.htmlを開き、正しく表示されていることを確認してください。

PDFドキュメントのビルド

PDF出力を行うには、LaTeX環境が必要です。
以下の手順でPDFを生成します。

LaTeXのインストール

LaTeXがインストールされていない場合は、以下のリンクからインストールしてください。
必要なパッケージのインストール

SphinxでPDFを生成する際に必要なLaTeXパッケージが不足している場合があります。
エラーメッセージに従って追加のパッケージをインストールしてください。
PDFのビルド

sourceディレクトリ内で以下のコマンドを実行します。
```
make latexpdf
```
生成されたPDFはbuild/latexディレクトリ内にあります。your_project_name.pdfなどのファイル名で出力されます。

注意: Mermaid図はPDF出力時に正しく表示されない場合があります。
その場合は、SVGやPNG形式の図を使用するか、別途調整が必要です。

トラブルシューティング

Mermaid図が正しく表示されない
- sphinxcontrib-mermaidが正しくインストールされ、conf.pyで拡張機能が有効になっているか確認してください。
- Mermaidのバージョンが最新であることを確認してください。
- ブラウザの開発者ツールでJavaScriptエラーが発生していないか確認します。
ビルドエラーが発生する
- conf.pyの設定に誤りがないか確認してください。
- ドキュメントファイル（.rst）の構文エラーがないか確認します。

依存関係の問題

仮想環境を再作成し、必要なパッケージを再インストールすることで解決する場合があります。

deactivate
rm -rf sphinx_env
python -m venv sphinx_env
source sphinx_env/bin/activate  # Windowsの場合は sphinx_env\Scripts\activate
pip install sphinx sphinxcontrib-mermaid

HTMLテーマが適用されない
- テーマが正しくインストールされているか確認してください。
- conf.pyでhtml_themeの設定が正しいか確認してください。
- テーマ固有のオプションを設定している場合、その設定が正しいか確認してください。

まとめ

Sphinxを使用することで、要件定義書、基本設計書、詳細設計書などの複数のドキュメントを統合し、Mermaidを活用した図を含む視覚的に優れたドキュメントを生成することができます。
さらに、HTMLテーマを選択することで、ドキュメントの見た目をカスタマイズし、PDF出力機能を活用することでオフラインでの閲覧も可能です。

参考リンク