【驚愕】たった3ステップでMarkdownが美しいドキュメントに変身！Sphinxと関連ライブラリ導入ガイド

# はじめに

前回の記事では、Sphinxを用いて要件定義書、基本設計書、詳細設計書などの複数のドキュメントを統合し、Mermaidを活用した図を含むドキュメントを生成する方法について解説しました。

https://qiita.com/syukan3/items/07243155c38c41b3b1e4

本記事では、その続編として、Sphinxで**Markdown**を使用する方法について詳しく説明します。
Markdownを利用することで、より直感的かつ効率的にドキュメントを作成・管理できるようになります。


以下は、SphinxとMarkdownを組み合わせて効果的なドキュメントを作成するための最終版ブログ記事です。各ライブラリの解説を含め、`conf.py`の設定方法も詳細に説明しています。重複を避け、公開直前に整えた内容となっています。

## Markdownとは

**Markdown**は、軽量マークアップ言語の一つで、テキストを簡潔かつ読みやすい形式で記述できることが特徴です。HTMLへの変換も容易であり、ブログ記事やREADMEファイル、技術文書など、さまざまな場面で利用されています。Sphinxでは、標準でreStructuredText（reST）がサポートされていますが、Markdownを使用することで、より馴染みやすい記法でドキュメントを作成できます。

## SphinxでMarkdownを使用するための準備

SphinxでMarkdownを使用するためには、専用のパーサーを導入する必要があります。現在では、`MyST-Parser`が最も一般的に使用されています。以下の手順で設定を行います。

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

まず、`MyST-Parser`をインストールします。前回設定した仮想環境がアクティブな状態で以下のコマンドを実行してください。

```bash
pip install myst-parser
```

また、Markdownを用いる際に便利な拡張機能も合わせてインストールすると良いでしょう。

```bash
pip install sphinx_markdown_tables
```

さらに、以下のライブラリもインストールしておくことで、ドキュメント作成がより効率的になります。

```bash
pip install sphinx-copybutton sphinxcontrib-mermaid furo sphinx-diagrams
```

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

次に、Sphinxプロジェクトの設定ファイルである`conf.py`を編集し、インストールした各ライブラリを有効にします。以下は、すべてのライブラリを統合した`conf.py`の設定例です。

```python
# conf.py

# -- プロジェクト情報 -----------------------------------------------------
project = 'My Project'
author = 'Author Name'
release = '1.0'

# -- 拡張機能の設定 -----------------------------------------------------
extensions = [
    'myst_parser',                  # Markdownサポート
    'sphinxcontrib.mermaid',        # Mermaid図表描画
    'sphinx_markdown_tables',       # Markdownテーブルのサポート
    'sphinx_copybutton',            # コピーボタンの追加
    'sphinx_diagrams',              # 図表描画
    # 他の拡張機能があればここに追加
]

# -- テーマの設定 ---------------------------------------------------------
html_theme = 'furo'                 # Furoテーマを使用

# -- ソースファイルの拡張子の設定 -----------------------------------------
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

# -- Masterドキュメントの設定 --------------------------------------------
master_doc = 'index'

# -- MyST-Parserの設定 ----------------------------------------------------
myst_enable_extensions = [
    "dollarmath",        # インラインおよびブロック数式のサポート
    "amsmath",           # AMS math機能のサポート
    "colon_fence",       # コロンフェンスのサポート
    "deflist",           # 定義リストのサポート
    "html_admonition",   # HTML警告のサポート
    "html_image",        # HTML画像のサポート
]

# -- sphinx_copybuttonの設定 ---------------------------------------------
copybutton_prompt_text = '>>> '    # コードブロックのプロンプトテキスト
copybutton_prompt_is_regexp = True  # プロンプトテキストを正規表現として扱う

# -- sphinxcontrib.mermaidの設定 -----------------------------------------
mermaid_output_format = 'svg'        # Mermaid図の出力形式

# -- sphinx_diagramsの設定 ------------------------------------------------
# sphinx_diagramsは特別な設定は不要ですが、必要に応じて設定を追加します

# -- HTML静的ファイルの設定 -----------------------------------------------
html_static_path = ['_static']

# -- カスタムCSSの設定 ----------------------------------------------------
html_css_files = [
    'custom.css',
]
```

#### 各設定項目の詳細説明

##### 1. `extensions`

インストールした各拡張機能を`extensions`リストに追加します。これにより、Sphinxはビルド時にこれらの拡張機能を使用します。

- `'myst_parser'`: Markdownサポートを有効にします。
- `'sphinxcontrib.mermaid'`: Mermaid.jsを使用した図表描画をサポートします。
- `'sphinx_markdown_tables'`: Markdownで記述したテーブルを適切にレンダリングします。
- `'sphinx_copybutton'`: コードブロックに「コピー」ボタンを追加します。
- `'sphinx_diagrams'`: 図表描画をサポートします。

```python
extensions = [
    'myst_parser',
    'sphinxcontrib.mermaid',
    'sphinx_markdown_tables',
    'sphinx_copybutton',
    'sphinx_diagrams',
    # 他の拡張機能があればここに追加
]
```

##### 2. `html_theme`

`html_theme`に`'furo'`を設定することで、Furoテーマを使用します。Furoはモダンでレスポンシブなテーマで、クリーンなデザインが特徴です。

```python
html_theme = 'furo'
```

##### 3. `source_suffix`

`source_suffix`辞書に`.md`拡張子を追加することで、Markdownファイルをソースとして認識させます。これにより、`.md`ファイルもビルド対象となります。

```python
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}
```

##### 4. `myst_enable_extensions`

`MyST-Parser`の拡張機能を有効にするための設定です。これにより、Markdown内でSphinx特有の機能（ディレクティブやロール、数式など）を利用可能になります。

```python
myst_enable_extensions = [
    "dollarmath",        # インラインおよびブロック数式のサポート
    "amsmath",           # AMS math機能のサポート
    "colon_fence",       # コロンフェンスのサポート
    "deflist",           # 定義リストのサポート
    "html_admonition",   # HTML警告のサポート
    "html_image",        # HTML画像のサポート
]
```

##### 5. `sphinx_copybutton`の設定

`sphinx_copybutton`の動作をカスタマイズします。例えば、コードブロック内のプロンプト（`>>> `など）をコピー時に無視する設定です。

```python
copybutton_prompt_text = '>>> '    # コードブロックのプロンプトテキスト
copybutton_prompt_is_regexp = True  # プロンプトテキストを正規表現として扱う
```

##### 6. `sphinxcontrib.mermaid`の設定

Mermaid図の出力形式を指定します。ここではSVG形式を使用しています。

```python
mermaid_output_format = 'svg'        # Mermaid図の出力形式
```

##### 7. `html_static_path` と `html_css_files`

カスタムCSSを適用するための設定です。`_static`ディレクトリに配置した`custom.css`を読み込みます。

```python
html_static_path = ['_static']

html_css_files = [
    'custom.css',
]
```

`custom.css`を使用して、テーマや拡張機能によって生成される要素のスタイルをカスタマイズできます。例えば、以下のようなスタイルを追加できます。

```css
/* custom.css */

/* 例: ノートの背景色を変更 */
.admonition.note {
    background-color: #f0f8ff;
    border-left: 4px solid #2196F3;
}
```

##### 8. その他の設定

- `master_doc`: マスタードキュメントを指定します。通常は`'index'`で問題ありません。

  ```python
  master_doc = 'index'
  ```

- `release`: プロジェクトのリリースバージョンを指定します。

  ```python
  release = '1.0'
  ```

---

## Markdownファイルの作成と管理

設定が完了したら、実際にMarkdownファイルを作成し、Sphinxプロジェクトに統合していきます。

### 1. Markdownファイルの構造

プロジェクトの`source`ディレクトリ内に、`.md`拡張子のファイルを作成します。例えば、以下のようなファイル構造を想定します。

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

各ドキュメントファイルは、従来の`.rst`ファイルと同様に管理しますが、拡張子が`.md`となります。

### 2. `toctree`ディレクティブの設定

`index.md`ファイルを編集し、`toctree`ディレクティブを用いて他のMarkdownファイルを参照します。

```markdown
# プロジェクトのドキュメント

ようこそ、プロジェクトのドキュメントへ。

## 目次

```{toctree}
: maxdepth=2
: caption=目次

requirements
basic_design
detailed_design
```
```

`toctree`ディレクティブ内では、拡張子を除いたファイル名を記述します。これにより、`requirements.md`、`basic_design.md`、`detailed_design.md`が目次に表示され、順番に統合されます。

---

## 拡張機能の活用

MarkdownをSphinxで使用する際、`MyST-Parser`を活用することで、Sphinx独自の機能をMarkdown内で利用できます。以下に、主な拡張機能とその使用方法を紹介します。

### 1. MyST-Parserの紹介

`MyST-Parser`（Markedly Structured Text）は、Markdownを拡張し、Sphinxの機能を統合するためのパーサーです。以下の機能を提供します。

- **ディレクティブとロールのサポート**: reSTで利用できるディレクティブやロールをMarkdownでも使用可能。
- **数学記法のサポート**: LaTeX形式での数式記述が可能。
- **コードブロックの拡張**: 複数行のコードやシンタックスハイライトの強化。

### 2. MySTの基本的な使用方法

#### ディレクティブの使用

ディレクティブを使用することで、特定の機能をMarkdown内に組み込むことができます。例えば、ノートを追加する場合は以下のように記述します。

```markdown
```{note}
これはノートです。重要な情報を強調できます。
```
```

#### 数式の挿入

LaTeX形式の数式を挿入することができます。

インライン数式:

```markdown
これはインライン数式の例です: $E = mc^2$。
```

ブロック数式:

```markdown
$$
\int_{a}^{b} f(x) dx
$$
```

#### テーブルの作成

Markdownの標準的なテーブル記法に加え、`sphinx_markdown_tables`を利用することで、より複雑なテーブルも作成可能です。

```markdown
| ヘッダー1 | ヘッダー2 | ヘッダー3 |
|-----------|-----------|-----------|
| データ1   | データ2   | データ3   |
| データ4   | データ5   | データ6   |
```

---

## テーマの調整とカスタマイズ

前回の記事では、**Furo**、**sphinx_rtd_theme**、**sphinx_material**といったテーマの選択と設定方法を紹介しました。Markdownを使用する際にも、これらのテーマは問題なく適用できます。ただし、テーマによってはスタイルの調整が必要な場合があります。

### 1. テーマの互換性確認

Markdownを使用する際、一部のテーマではスタイルが崩れる可能性があります。特に、カスタムCSSを使用している場合は、Markdown特有の要素に対応するスタイルを追加することを検討してください。

### 2. カスタムCSSの追加

`conf.py`にカスタムCSSを追加することで、Markdownで生成される要素のスタイルを調整できます。

```python
# conf.py

html_static_path = ['_static']

html_css_files = [
    'custom.css',
]
```

`source/_static/custom.css`ファイルを作成し、必要なスタイルを記述します。

```css
/* custom.css */

/* 例: ノートの背景色を変更 */
.admonition.note {
    background-color: #f0f8ff;
    border-left: 4px solid #2196F3;
}
```

---

## ビルドと確認

Markdownを使用したドキュメントのビルドは、前回と同様に`make`コマンドを使用します。以下の手順でビルドを行い、正しく表示されているか確認します。

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

```bash
make html
```

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

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

Markdownを使用する場合も、PDF出力は前回と同様に`latexpdf`ターゲットを使用します。

```bash
make latexpdf
```

生成されたPDFは`build/latex`ディレクトリ内に保存されます。数式や図が正しく表示されているか確認しましょう。

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

---

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

Markdownを使用する際に発生しやすい問題とその解決方法を紹介します。

### 1. Markdownファイルが認識されない

- **原因:** `conf.py`で`.md`拡張子が正しく設定されていない。
- **解決策:** `conf.py`の`source_suffix`に`.md`が含まれていることを確認します。

```python
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}
```

### 2. ディレクティブが正しく動作しない

- **原因:** `MyST-Parser`が正しくインストール・設定されていない。
- **解決策:** `conf.py`の`extensions`に`'myst_parser'`が含まれていることを確認し、パッケージがインストールされているか確認します。

```python
extensions = [
    'myst_parser',
    # 他の拡張機能
]
```

### 3. 数式が表示されない

- **原因:** MathJaxやLaTeXの設定が不十分。
- **解決策:** `conf.py`で数式のサポートが有効になっていることを確認します。

```python
# conf.py

extensions = [
    'myst_parser',
    'sphinxcontrib.mermaid',
    # 他の拡張機能
]

myst_enable_extensions = [
    "dollarmath",
    "amsmath",
    "colon_fence",
    "deflist",
    "html_admonition",
    "html_image",
]
```

### 4. テーマが崩れる

- **原因:** カスタムCSSの競合やテーマの互換性問題。
- **解決策:** カスタムCSSを見直し、必要に応じてテーマのドキュメントを参照して調整します。

---

# まとめ

今回の記事では、Sphinxで**Markdown**を使用する方法について解説しました。`MyST-Parser`を導入することで、Sphinxの強力なドキュメント生成機能をMarkdownのシンプルな記法と組み合わせて利用できます。これにより、技術文書の作成がより直感的かつ効率的になります。

**ポイントまとめ:**

- **ライブラリのインストール**: `pip`コマンドを使用して、Sphinx本体および各種拡張機能やテーマをインストール。
- **`conf.py`の設定**: インストールしたライブラリを`extensions`リストに追加し、テーマやその他の設定を行う。
- **カスタムCSS**: 必要に応じてカスタムCSSを追加し、ドキュメントの見た目を調整。
- **拡張機能の活用**: Mermaidによる図表描画、Markdownテーブル、コピーボタンなど、各拡張機能を活用してドキュメントの利便性を向上。

これらの手順を踏むことで、SphinxとMarkdownを組み合わせた強力なドキュメント作成環境を構築し、効率的かつ直感的に技術文書を管理・生成できます。

---

## 参考資料

- [MyST-Parser公式ドキュメント](https://myst-parser.readthedocs.io/)
- [Sphinx公式ドキュメント](https://www.sphinx-doc.org/ja/master/)
- [sphinx_markdown_tables GitHub](https://github.com/ryanfox05/sphinx-markdown-tables)
- [Furoテーマ公式サイト](https://pradyunsg.me/furo/)
- [sphinx_rtd_theme GitHub](https://github.com/readthedocs/sphinx_rtd_theme)
- [sphinx_material公式ドキュメント](https://sphinx-material.readthedocs.io/)
- [sphinxcontrib-mermaid GitHub](https://github.com/mgaitan/sphinxcontrib-mermaid)
- [sphinx_copybutton GitHub](https://github.com/executablebooks/sphinx-copybutton)
- [sphinx_diagrams GitHub](https://github.com/mgaitan/sphinx_diagrams)

---
### 会社紹介

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

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