Sphinx から完全に reStructuredText を追い出した話
いくつかの記事で紹介されているとおり、 recommonmark を使うと Sphinx で markdown を使うことができます。
- Software Design 2016年4月号 Markdownで始めるSphinx
- MarkdownでSphinxできるようになったので試してみた（前編） - 意識の高いLISPマシン
- Markdownで書けるSphinxの構築 - Qiita
しかし、recommonmark を利用しても、ドキュメント構造(toctree)を記述するためには部分的に reStructredText を使う必要がありました。
.. toctree chapter1 chapter2 chapter3
これは、文法を拡張する仕組みを持たない markdown の (commonmark の)構造上、仕方がないのですが、せっかく markdown でドキュメントを書いているに、一部 reST 記法を使わなくてはならないのは、少しもにょっとしますね。
どうせなら、完全に reST を書かなくてもよい仕組みがほしいところです。
sphinxcontrib-toc
ということで、sphinxcontrib-toc を作りました。
sphinxcontrib-toc は toctree を表現する .toc ファイルを用意することで、reST を書かずにドキュメントを作ることができます。
使い方はたったの 3ステップです。
1. 以下のコマンドでインストールします。
$ pip install sphinxcontrib-toc
2. conf.py で拡張を有効にします。
extensions = ['sphinxcontrib.toc']
3. index.toc というファイルに、ドキュメントを構成するファイルを列挙します。
chapter1 chapter2 chapter3 ...
4. 最後に、不要となった index.rst を削除します。
$ rm index.rst
あとはビルドするだけです。
$ make html
大きいドキュメントを書くときは
大きいドキュメントを書きたい場合は、複数の .toc ファイルを作り、親の .toc ファイルから子の .toc ファイルを参照します。
chapter1/index chapter2/index chapter3/index
そして、子の .toc ファイルにはその章や節を構成するファイルを列挙します。
# 章タイトル section1 section2 section3
子の .toc ファイルでは markdown のタイトル記法を使って章や節のタイトルが指定できます。
(省略した場合はドキュメントのタイトルが適用されます)
sphinxcontrib-toc の仕組み
sphinxcontrib-toc は .toc ファイルを通じて toctree を生成します。
内部ではあたらしいファイルタイプを Sphinx に登録し、.toc ファイルが見つかるたびに sphinxcontrib-toc が呼び出されるようになっています。
そして、sphinxcontrib-toc は .toc ファイルをパースして、toctree を生成します。
これは 1.4 から導入されたソースパーサ(Source Parser)という仕組みを使っています。recommonmark もソースパーサのひとつですから、じつはふたつのモジュールは同種の拡張として実装されています。
.toc ファイルは設定ファイルのような見かけですが、実はドキュメントとして処理されています。
これで完璧!?
さて、これで Sphinx と markdown の組み合わせでドキュメントを作ることができます。
github や qiita、そのたたくさんのプラットフォームで使われている markdown でドキュメントが書けるのです！最高ですね！
と盛り上げてみたものの、実際書いていくと、まだ問題はいくつか残っています。
- recommonmark は CommonMark の範囲のマークアップしかできない
- 表、定義リスト、脚注、顔文字などを書けない
- recommonmark はディレクティブやロールが使えない
前者については、commonmark の仕様上の問題ですので、recommonmark に代わる別の markdown パーサが出てくるのを待つ必要があります。
個人的な実験プロジェクトとして sphinxcontrib-markdown というのを作りかけのままにしていますが、これが完成すると github flavored markdown にも対応したものができるはずです。
興味がある方は手伝っていただけると非常にありがたいです。
後者は markdown の文法をさらに大きく変えることになります。
利便性は高くなりますが、あらたな markdown 方言を生み出すことになります。
実は recommonmark にも AutoStructify という拡張文法が存在します。しかし、こうした方言を利用した場合、別の処理系にはドキュメントを持ち運ぶことができなくなります。
ここはトレードオフになる部分ですので、どのようにマークアップすべきかも含めて、ツール選びを検討すると良いでしょう。
