Sphinx で文書の記述に markdown を使う

はじめに

Sphinx では、文書の記述に reStructuredText を使うのが基本です。

しかし Markdown 全盛の時代では、新しく reStructuredText を覚えるよりも Markdown で書きたいと考える方も多いことでしょう。それはやはり自然なことです ¹ 。

commonmark が使える

Sphinx 関連のツール（プラグイン？）の recommonmark を使うと、commonmark なら使えるようになります。

インライン reStructuredText

また、commonmark で物足りない場合（表など）は、また別のプラグインを用いることで Markdown の中でインラインの reStructuredText を表現できる等、幅が広がります。詳しいことは、下記のリンクを参照してみてください。

Sphinxを便利にして、みんなに使ってもらいたい - Qiita

すでに Markdown ドキュメントがたくさんある

しかしながら、Markdown にまた新しい方言が生まれることに抵抗を感じるかもしれません ² 。あるいは既に蓄積された Markdown ドキュメントに手を加える工数をかけられないケースもあるでしょう。

そこで、文書変換ツール Pandoc を使って、複数の Markdown ファイルを reStructuredText に一括変換します。

Windows 用 Sphinx にて quickstart すると make.bat が作成されます。その冒頭に以下の処理を追加します。

    for /R %%f in (*.md) do (
        pandoc --toc -f markdown_github+hard_line_breaks+pipe_tables -t rst -s -o "%%‾dpf%%‾nf.rst" %%f%
    )

ついでにシェル版も書いておきます。

#! /usr/bin/sh

for file in `\find . -name '*.md'`; do
    dir=`dirname $file`/
    fn=`basename $file .md`
    pandoc --toc -f markdown_github+hard_line_breaks+pipe_tables -t rst -s -o "$dir$fn.rst" $file
done

これにより、.md ファイルを .rst ファイルに変換してから make が走ってくれるようになります。

Pandoc にてどのような Markdown が使えるのかは Pandoc ユーザーズガイド 日本語版 の 一般的なオプション を参照してください。

両刀は苦ではない

ちなみに私は一つのプロジェクトでこのバッチ処理を使いましたが、結局は reStructuredText を使った方が拡張性が高いし手っ取り早いと思って reStructuredText に移行しました。

でも Sphinx に入れない程度のメモなどには Markdown を使っています。

両刀は別に苦ではないです。ならなくなりました。

はじめてのMarkdown―軽量マークアップ言語の記法と使い方 (I・O BOOKS)

Atom実践入門──進化し続けるハッカブルなエディタ (WEB+DB PRESS plus)

---

1. 私もそう思っていたのですが、reStructuredText も直に覚えました。食わず嫌いというか、なんか尻込みしていたのがバカバカしくなりました。↩

2. 方言というか「Sphinx のための拡張」と行った方が正確かもしれません。↩