Sphinx 文書に markdown フォーマットを利用する

markdown と Sphinx (reST)

Sphinx では文書を書く際の記述フォーマットに reStructured Text を利用していますが、
世を広く見回すと、github 然り、bitbucket 然り、様々な場所で markdown フォーマットが利用されています。
markdown フォーマットは reST と比べると表現力が低い上、表現を拡張することができないという点が指摘されています。
表現を拡張することができないため、いくつかの方言が存在するという問題もあります。

ですが、reST と比べてシンプルで、なおかつポピュラーに利用されているフォーマットであるため、
新しく Sphinx に触り始める人の取っ掛かりとしては、markdown はうってつけのフォーマットと言えます。

sphinxcontrib_markdown

それでは、Sphinx を markdown を利用するための拡張 sphinxcontrib_markdown を利用します。
今しがた作ったばかりの新しいプログラムなので、gist からソースコードを保存してください。

$ wget https://gist.github.com/raw/4336929/25dfcaad2b2d63a973617757062cec3ab9c31c35/sphinxcontrib_markdown.py

そして、conf.py に以下の記述を追加します。

sys.path += ["."]
extensions += ["markdown"]
 
markdown_title = 'hello world'
source_suffix = '.md'

そして、markdown で書かれた文章を Sphinx プロジェクトディレクトリに配置します。
なお、この時に index.md というファイル名は利用しないでください。

あとは、いつもどおり make を実行します。

$ make html

そうすると、markdown を Sphinx で変換した HTML を得ることができます。
もちろん PDF や ePub にも変換することが可能です。

sphinxcontrib_markdown の仕組み

sphinxcontrib_markdown は Sphinx が markdown ファイルを読み込む際に、
pandoc を利用して自動的に reST フォーマットへ変換して Sphinx に取り込んでいます。

また、markdown には toctree に相当するものがなく、各ページをつなぐ目次を生成することができないため、
sphinxcontrib_markdown モジュールでは、ソースとなる markdown ファイルすべてに対する toctree を自動的に生成します。
そのため、make html を実行すると自動的に index.md が生成されます。

まとめ

今日は Sphinx から markdown フォーマットを利用するための sphinxcontrib_markdown モジュールを作成しました。
内部では様々なイベントハンドラを利用したり、Sphinx に実行時パッチを当てて動きを変えたりと、
割と無茶なことをしていますが、Pro GIT を変換してみたところ
特にエラーなく Sphinx ドキュメントとして変換することができました。(一部 pandoc 由来のワーニングが出ます)

僕自身は普段まったく markdown を書かないため、「作ってみた」に近い状態ですので、
どなたか実際に使ったりいじったりして、突っ込んでもらえると助かります。

では、明日は @r_rudi さんの番です。楽しみにしてます :-)