IT系のお仕事をしている人には経験があると思いますが、面倒な事の１つがドキュメントの作成です。
納品するシステムのドキュメント、
チーム間でシェアするシステムのAPIドキュメントなど多種多様です。
筆者もITベンダーに入社したての頃はWordでドキュメントの作成をしていまいました。
フォントや文字の大きさ、フォーマットを揃えて、
その後キャプチャーを撮って 画像を貼り付けたり ... etc
とにかく面倒だった思い出しか残っていません。
幸いにも現在のドキュメント作成にはSphinx等を代表するドキュメントジェネレーターがありますが、
Sphinxは "ReStructuredText"というマークアップ言語で記述するので少々慣れが必要です。
"どうせならMarkdown形式で記述出来たらいいのに、、"
という時に便利なパッケージが "MkDocs"です。
MkDocsはSphinxと同じくPythonで作られており
インストールからドキュメント作成まで簡単に行えます。
それでは少し試してみましょう！
( 今回の検証にはPython v 3.5.1 を使いました )
MkDocsのインストールにはpip ( Pythonのパッケージ管理システム ) が必要になります。
# pipのインストール
easy_install pip
pipをインストールした後、
下記のコマンドをターミナル上で叩くとMkDocsのインストールが開始されます。
# MkDocsのインストール
pip install mkdocs
インストールが完了すると"mkdocs"コマンドが使えるようになり、
"mkdocs new <ドキュメントのプロジェクト名>"でプロジェクトが作成されます。
# プロジェクトの作成コマンド (今回は my-docという名で作成しました)
mkdocs new my-doc
以下が "mkdocs new " コマンドで作成されたMkDocsのファイル群です。
ymlファイルとdocフォルダ、MarkDownファイルが１つずつ作成されるというシンプルな構成になっていますね。
- my-doc # プロジェクトルート
- docs # このフォルダにドキュメントを作っていきます
index.md
mkdocs.yml # 設定情報を書くconfigファイル
ここでMkDocsを動かしてみましょう！
プロジェクトルートで下記のコマンドを打つとpythonのサーバーが起動し、
ブラウザで" http://localhost:8000/ "にアクセスするとドキュメントのプロジェクトが表示されます。
mkdocs serve # serverの起動コマンド
docsフォルダ内にMarkDownファイルを追加すると サーバーに反映されページが追加されます。
試しに下記の様にフォルダとファイルを追加してみました。
- docs
- testDir # 追加したフォルダ
TestDoc.md # 追加したファイル
example.md # 追加したファイル
index.md
tabスペースを２つ追加するとプログラミングコードと見なされ、自動的にハイライトされます。
[//]: <> (MarkDownのコメント)
## C++スニペット
#include
int main()
{
std::cout << "Hello, world!" << std::endl;
return 0;
}
MkDocsのデザインはデフォルトテーマを含む15種類が用意されており、
mkdocs.ymlファイルにテーマ情報を追加することにより簡単に変更出来ます。
( その他にもカスタムCSSを使う事も出来ます )
# mkdocs.yml
theme: readthedocs #テンプレートのテーマ
- mkdocs # デフォルトテーマ
- readthedocs
# bootstrapを使ったテーマ
- bootstrap
- amelia
- cerulean
- cosmo
- cyborg
- flatly
- journal
- readable
- simplex
- slate
- spacelab
- united
- yeti
MkDocsはSphinxと同様に静的ファイルにコンパイルすることが出来ます。
下記のコマンドを打つと”site”フォルダが作成され
htmlファイル,css等の静的ファイルが発行され、pythonサーバーの起動無しでも
ドキュメントを見ることが出来るようになります。
また、html形式だけではなく、json形式にもビルドが可能。
mkdocs build # htmlファイルにビルド
mkdocs json # json形式にビルド
MkDocsを使うとMarkDown形式で記述出来るので、
簡単に素早くドキュメント作成が出来そうです。
実際のプロジェクトで使う時も静的ファイルに変換されるので、
Webのプロジェクトではpublicフォルダ内に直接置くことも可能ですね。
次のプロジェクトではMkDocsを使ってみては如何でしょうか！
MkDocs
