MarkdownでSphinxできるようになったので試してみた（前編）

この記事は ドキュメンテーションツールAdvent Calendar の1日目です。

（まだまだ空欄だらけなので、執筆者も募集しています。）

www.adventar.org

私はMarkdownで普段文書を書いているのですが、 この度ドキュメンテーションツール Sphinx でMarkdownが使えるようになったと聞いたので、軽く試してみたいと思います。

この記事は2部構成で2日にわたって執筆されます。

• 1日目：概要の説明（いまここ）
• 2日目：実際に試してみた記録（予定）

今回の記事では、概要をざっと説明します。

背景：Markdownの標準規格「CommonMark」の制定

MarkdownはGitHub Flavoredをはじめとして色々な方言があり、 まとまった仕様もなく混乱していました。

その中に現れたのが、CommonMarkというMarkdownの標準化規格です。

CommonMark

Pandoc の作者であるJohn MacFarlaneなどの委員会メンバーを中心に、 構文解析が厳密にできるように注意深く策定されました。 2015/08/23時点のバージョンは0.22です。

日本語の記事もあります。（この記事を読むと、規格がまとまるまでに波瀾万丈があったことが分かります。）

Standard MarkdownがCommon Markdow、そしてCommonMarkに

Sphinxとは

概要 — Sphinx 1.3.2 ドキュメント より色々引用。

Sphinxは知的で美しいドキュメントを簡単に作れるようにするツールです。

このツールはもともと、新しいPythonのドキュメントの変換のために作られました。

Sphinx特徴的な機能を以下に紹介します:

• 出力形式: HTML (WIndowsのHTMLヘルプを含む)、LaTeX(印刷可能なPDFバージョン)、ePub、Texinfo、man、プレーンテキスト
• 多岐にわたる相互参照: 意味のマークアップと、関数、クラス、引用、用語解説、似たような情報に対する自動リンク
• 階層構造: 簡単にドキュメントツリーを定義でき、兄弟、親、子供のドキュメントに対して、リンクを貼れる
• 自動インデックス作成: 全体インデックスと、言語特有のモジュールインデックス
• ソースコードの対応: Pygmentsを使った自動ハイライト
• æ‹¡å¼µ: コードスニペットを使った自動テスト, Pythonモジュールのdocstringのインクルード(APIドキュメント作成), 他にもあります
• 寄贈された拡張: 50以上の拡張が ユーザによって寄贈され。 sphinx-contribリポジトリ内にあり、ほとんどの拡張はPyPIよりインストール可能

SphinxでMarkdownできるぞ！

最近、SphinxにCommonMarkパーサ（つまりMarkdownパーサ）が搭載されたようです。 このプレゼンがきっかけで知りました。

というわけで、Markdown党にとっては念願の「Sphinxを使ったMarkdown文書の変換」が実現できるようです。これから実際に試してみます。

この次の話

以上で1日目（概要の説明）は終わりです。 2日目で、実際にインストールして文書を生成してみます（予定）。