意識の高いLISPマシン

藤原惟/すかいゆき(@sky_y)の技術用ブログ

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日目で、実際にインストールして文書を生成してみます(予定)。