サポンテ 勉強ノート

サポンテの勉強ノート・読書メモなどを晒します。

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

はじめに

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

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

commonmark が使える

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

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

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

それでも

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

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

WindowsSphinx にて 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 を使っています。

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

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

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


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

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

広告を非表示にする