Sphinxで統合ドキュメントを作成し、Mermaid図を活用する方法

# はじめに

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

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


## 前提条件

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

## 環境のセットアップ

1. **Pythonのインストール確認**

   ターミナル（コマンドプロンプト）で以下のコマンドを実行し、Pythonがインストールされていることを確認します。

   ```bash
   python --version
   ```

   例：

   ```
   Python 3.9.7
   ```

   インストールされていない場合は、[Python公式サイト](https://www.python.org/downloads/)からインストールしてください。

2. **仮想環境の作成（推奨）**

   プロジェクトごとに依存関係を管理するために、仮想環境を作成します。

   ```bash
   python -m venv sphinx_env
   ```

   仮想環境をアクティブにします。

   - **Windows:**

     ```bash
     sphinx_env\Scripts\activate
     ```

   - **macOS/Linux:**

     ```bash
     source sphinx_env/bin/activate
     ```

## Sphinxプロジェクトの初期化

1. **Sphinxのインストール**

   仮想環境がアクティブな状態で、Sphinxをインストールします。

   ```bash
   pip install sphinx
   ```

2. **Sphinxプロジェクトの作成**

   プロジェクト用のディレクトリを作成し、そこに移動します。

   ```bash
   mkdir my_documentation
   cd my_documentation
   ```

   Sphinxの初期化コマンドを実行します。

   ```bash
   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`拡張機能を追加します。

1. **必要なパッケージのインストール**

   ```bash
   pip install sphinxcontrib-mermaid
   ```

2. **`conf.py`の設定**

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

   ```python
   # conf.py

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

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

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

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

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

1. **ディレクトリ構造の例**

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

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

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

   - **requirements.rst**

     ```rst
     Requirements
     ============
     
     要件定義書の内容をここに記述します。
     
     .. mermaid::

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

   - **basic_design.rst**

     ```rst
     Basic Design
     ============
     
     基本設計書の内容をここに記述します。
     
     .. mermaid::

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

   - **detailed_design.rst**

     ```rst
     Detailed Design
     ===============
     
     詳細設計書の内容をここに記述します。
     
     .. mermaid::

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

3. **`index.rst`の編集**

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

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

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

- **インストール**

  ```bash
  pip install furo
  ```

- **設定**

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

  ```python
  # conf.py

  html_theme = 'furo'
  ```

### 2. Read the Docsテーマ (sphinx_rtd_theme)

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

- **インストール**

  ```bash
  pip install sphinx_rtd_theme
  ```

- **設定**

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

  ```python
  # conf.py

  html_theme = 'sphinx_rtd_theme'
  ```

### 3. Sphinx Material

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

- **インストール**

  ```bash
  pip install sphinx-material
  ```

- **設定**

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

  ```python
  # conf.py

  html_theme = 'sphinx_material'

  # オプション設定（例）
  material_theme_color = 'blue'
  material_logo = 'path/to/logo.png'
  ```

  **注意:** `sphinx_material` は追加の設定オプションが豊富です。詳細は[公式ドキュメント](https://sphinx-material.readthedocs.io/)を参照してください。

## ドキュメントのビルド

### HTMLドキュメントのビルド

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

```bash
make html
```

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

### PDFドキュメントのビルド

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

1. **LaTeXのインストール**

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

   - [TeX Live (Windows/macOS/Linux)](https://www.tug.org/texlive/)
   - [MacTeX (macOS専用)](https://www.tug.org/mactex/)
   - [MiKTeX (Windows専用)](https://miktex.org/)

2. **必要なパッケージのインストール**

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

3. **PDFのビルド**

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

   ```bash
   make latexpdf
   ```

   生成されたPDFは`build/latex`ディレクトリ内にあります。`your_project_name.pdf`などのファイル名で出力されます。

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

## トラブルシューティング

1. **Mermaid図が正しく表示されない**

   - `sphinxcontrib-mermaid`が正しくインストールされ、`conf.py`で拡張機能が有効になっているか確認してください。
   - Mermaidのバージョンが最新であることを確認してください。
   - ブラウザの開発者ツールでJavaScriptエラーが発生していないか確認します。

2. **ビルドエラーが発生する**

   - `conf.py`の設定に誤りがないか確認してください。
   - ドキュメントファイル（.rst）の構文エラーがないか確認します。

3. **依存関係の問題**

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

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

4. **HTMLテーマが適用されない**

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

## まとめ

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


# 参考リンク

- [Sphinx公式ドキュメント](https://www.sphinx-doc.org/ja/master/)
- [sphinxcontrib-mermaid GitHub](https://github.com/mgaitan/sphinxcontrib-mermaid)
- [Furoテーマ公式サイト](https://pradyunsg.me/furo/)
- [sphinx_rtd_theme GitHub](https://github.com/readthedocs/sphinx_rtd_theme)
- [sphinx_material公式ドキュメント](https://sphinx-material.readthedocs.io/)

---
### 会社紹介

**株式会社 Mosaica**  
最先端テクノロジーで社会課題を解決し、持続可能な未来を創造する IT カンパニー。
AI ソリューション、クラウド統合、DX 推進、経営コンサルティングなど包括的なサービスでビジネス変革を支援しています。  

詳しくは [公式サイト](https://mosaica.co.jp/) までお気軽にご相談ください。
公式サイト： https://mosaica.co.jp/