プロジェクトのドキュメントをどう記述し、どう管理するかは重要な問題です。やってはいけないのは一つのドキュメントにまとめて管理することです。大きな文書は修正しづらく、全体が密に連携するので一つの修正が他に及ぼす影響が分かりづらくなります。 文書はなるべく疎結合に、分割して管理されるべきです。しかもMarkdownフォーマットであればテキストファイルなので更新も検索も用意です。ということでMkDocsを紹介します。

MkDocsの使い方

MkDocsのインストールはpipで行います。

$ pip install mkdocs

まずはヘルプを出してみます。

$ mkdocs help
MkDocs (version 0.12.2)
mkdocs [help|new|build|serve|gh-deploy|json] {options}

newで新しいプロジェクトを作成します。設定ファイルなどが生成されます。

$ mkdocs new my-project
Creating project directory: my-project
Writing config file: my-project/mkdocs.yml
Writing initial docs: my-project/docs/index.md

ファイル構成は次のようになります。

$ tree
.
├── docs
│   └── index.md
└── mkdocs.yml

1 directory, 2 files

後はserveを使ってWebブラウザでプレビューできます。

実際のファイルはMarkdownです。

新しくファイルを作れば、それがメニューに反映されます。

プロジェクトのドキュメントは一つのフォルダの中にまとめて放り込まれることが多いですが、MkDocsを使えばそのドキュメントをWebブラウザから手軽に読めるようになるでしょう。

MkDocsはPython製、MIT Licenseのオープンソース・ソフトウェア（MIT License）です。

MkDocs mkdocs/mkdocs