Markdownで書けるSphinxの構築

背景

SphinxはPythonの各種ライブラリを始め様々なところで使用されているオープンソースのドキュメントシステムです。SphinxではreStructuredTextという軽量のマークアップ言語でドキュメントを記述しますが、今ではGitHubやQiitaなどのサービスに普及もあってMarkdownの方に慣れてしまっています¹。

そこでSphinxでもMarkdownで書ける環境を構築したいと思います。
recommonmarkというSphinxの拡張を使用します。

手順

virtualenvwrapperが使えるpython環境前提としています。

環境準備

$ mkvirtualenv sphinx
$ pip install sphinx recommonmark

プロジェクト生成

$ sphinx-quickstart 

設定

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

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

後は拡張子を.mdにしてドキュメントを書けば自動的にMarkdownとしてコンパイルされます。

---

1. あくまで個人的感想ですけど。。。 ↩