はじめに
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_documentationSphinxの初期化コマンドを実行します。
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出力機能を活用することでオフラインでの閲覧も可能です。