Sphinx より MkDocs

MkDocs に先立ち Sphinx を使ってみた。結論から言うと、もう Sphinx は使う必要がない。Read The Docs も MkDocs に対応しているので、わざわざ Sphinx にする必要はない。

	MkDocs	Sphinx
出力フォーマット	HTML,PDF,ePubなど	HTML,PDF,ePub,man,Texinfo,LaTeX,テキストファイルなど
HTMLのビルドと確認	静的に HTML をビルド+動的に確認可能	静的に HTML をビルド+別途ウェブサーバなどで確認
拡張性	可能(プラグイン)	可能(拡張機能)
テーマ	変更可能	変更可能
ドキュメントの書き方	MarkDown 記法(独自)	reStructuredText 記法(独自)
Read The Doc 対応	可能	可能

一番の違いは MD か reStructuredText かということ。reStructuredText 悪くないんだけど(MD よりは好み)、世の中的にはもうオワコンに近い気がするな。特にエディター初心者には MD の方が圧倒的に良い。

Python のドキュメント環境としてのみ Sphinx に一日の長があるかもしれないがC や C++ では Sphinx に全く強みなし。その上、Sphinx はちょっと難しいことをしようとすると途端にわからなくなる。

そもそも MkDocs て何よ

Markdownでドキュメントを書いて静的サイトを生成するPythonのパッケージです。MkDocsを使うことで、高品質で美しく見栄えのするWebサイトを簡単に作成できます。

インストール

まず、MkDocsをインストールします。あとなんだよくわからいけど mkdocs-material も入れておきます。ついでにわたしは mkdocs-asy も入れました。

$ pip install mkdocs

$ pip install mkdocs-material

$ pip install mkdocs-asy

プロジェクトの作成

MkDocsでウェブサイトを作成するためのプロジェクトを作成します。MkDocsを使用するフォルダに移動し、以下のコマンドを入力してください。

$ mkdocs new my-docs

これにより、my-projectという名前の新しいフォルダが作成され、MkDocsのプロジェクトが初期化されます。my-projectの中には、docsフォルダとmkdocs.ymlファイルが含まれています。

ドキュメントを書く

docsフォルダの中に、index.mdという名前のファイルが生成されています。このファイルを開いて、Markdownでドキュメントを書来ます。

index.md

# タイトル

これはサンプルのドキュメントです。

## セクション

これはセクションのテキストです。Lorem ipsum dolor sit amet, consectetur adipiscing elit.

### サブセクション

これはサブセクションのテキストです。Nullam commodo, nulla at molestie efficitur, magna quam varius augue, vel facilisis libero enim ut erat.

プレビュー

プレビューしてみます。ターミナルを開き、my-docsフォルダに移動し、mkdocs serveコマンドを入力します。これにより、ウェブサーバがローカルホスト上で開始されるので、ブラウザで表示可能になります。サイトのURLは、http://localhost:8000 です。この時点ではまだ build されていません。