MarkdownでSphinxできるようになったので試してみた（前編）
この記事は ドキュメンテーションツールAdvent Calendar の1日目です。
（まだまだ空欄だらけなので、執筆者も募集しています。）
私はMarkdownで普段文書を書いているのですが、 この度ドキュメンテーションツール Sphinx でMarkdownが使えるようになったと聞いたので、軽く試してみたいと思います。
この記事は2部構成で2日にわたって執筆されます。
- 1日目：概要の説明（いまここ）
- 2日目：実際に試してみた記録（予定）
今回の記事では、概要をざっと説明します。
背景：Markdownの標準規格「CommonMark」の制定
MarkdownはGitHub Flavoredをはじめとして色々な方言があり、 まとまった仕様もなく混乱していました。
その中に現れたのが、CommonMarkというMarkdownの標準化規格です。
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日目で、実際にインストールして文書を生成してみます（予定）。
