はじめに

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

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

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

Markdownとは

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

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

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

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

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

pip install myst-parser

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

pip install sphinx_markdown_tables

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

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

2. `conf.py`の設定

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

# 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': 図表描画をサポートします。

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

2. `html_theme`

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

html_theme = 'furo'

3. `source_suffix`

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

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

4. `myst_enable_extensions`

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

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

5. `sphinx_copybutton`の設定

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

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

6. `sphinxcontrib.mermaid`の設定

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

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

7. `html_static_path` と `html_css_files`

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

html_static_path = ['_static']

html_css_files = [
    'custom.css',
]

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

/* custom.css */

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

8. その他の設定

master_doc: マスタードキュメントを指定します。通常は'index'で問題ありません。
```
master_doc = 'index'
```
release: プロジェクトのリリースバージョンを指定します。
```
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ファイルを参照します。

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

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

## 目次

```{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$。

ブロック数式:

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

テーブルの作成

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

| ヘッダー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で生成される要素のスタイルを調整できます。

# conf.py

html_static_path = ['_static']

html_css_files = [
    'custom.css',
]

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

/* custom.css */

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

ビルドと確認

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

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

make html

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

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

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

make latexpdf

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

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

トラブルシューティング

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

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

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

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

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

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

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

3. 数式が表示されない

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

# 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を組み合わせた強力なドキュメント作成環境を構築し、効率的かつ直感的に技術文書を管理・生成できます。

参考資料

会社紹介

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

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