読者です 読者をやめる 読者になる 読者になる

Sphinx から完全に reStructuredText を追い出した話

いくつかの記事で紹介されているとおり、 recommonmark を使うと Sphinxmarkdown を使うことができます。

しかし、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 ファイルは設定ファイルのような見かけですが、実はドキュメントとして処理されています。

これで完璧!?

さて、これで Sphinxmarkdown の組み合わせでドキュメントを作ることができます。
github や qiita、そのたたくさんのプラットフォームで使われている markdown でドキュメントが書けるのです!最高ですね!

と盛り上げてみたものの、実際書いていくと、まだ問題はいくつか残っています。

  • recommonmark は CommonMark の範囲のマークアップしかできない
    • 表、定義リスト、脚注、顔文字などを書けない
  • recommonmark はディレクティブやロールが使えない
    • クラスリファレンスなどに便利な機能(ディレクティブ、参照、ドメインなど)が使えない
    • インデックス機能なども使えない
    • 一部の Sphinx 拡張は利用できない

前者については、commonmark の仕様上の問題ですので、recommonmark に代わる別の markdown パーサが出てくるのを待つ必要があります。
個人的な実験プロジェクトとして sphinxcontrib-markdown というのを作りかけのままにしていますが、これが完成すると github flavored markdown にも対応したものができるはずです。
興味がある方は手伝っていただけると非常にありがたいです。

後者は markdown の文法をさらに大きく変えることになります。
利便性は高くなりますが、あらたな markdown 方言を生み出すことになります。
実は recommonmark にも AutoStructify という拡張文法が存在します。しかし、こうした方言を利用した場合、別の処理系にはドキュメントを持ち運ぶことができなくなります。
ここはトレードオフになる部分ですので、どのようにマークアップすべきかも含めて、ツール選びを検討すると良いでしょう。

まとめ

  • 一発ネタで sphinxcontrib-toc を作ってみた
  • 作ってるうちに、割と使えるものになってしまった
  • markdown まわりを Sphinx でどう活用していくか、まだ迷っている部分があります
  • 使ってみて意見をください