IT系のお仕事をしている人には経験があると思いますが、面倒な事の1つがドキュメントの作成です。

納品するシステムのドキュメント、
チーム間でシェアするシステムのAPIドキュメントなど多種多様です。

筆者もITベンダーに入社したての頃はWordでドキュメントの作成をしていまいました。

フォントや文字の大きさ、フォーマットを揃えて、
その後キャプチャーを撮って 画像を貼り付けたり ... etc
とにかく面倒だった思い出しか残っていません。

幸いにも現在のドキュメント作成にはSphinx等を代表するドキュメントジェネレーターがありますが、
Sphinxは "ReStructuredText"というマークアップ言語で記述するので少々慣れが必要です。

"どうせならMarkdown形式で記述出来たらいいのに、、"
という時に便利なパッケージが "MkDocs"です。

MkDocsはSphinxと同じくPythonで作られており 
インストールからドキュメント作成まで簡単に行えます。

それでは少し試してみましょう!
( 今回の検証にはPython v 3.5.1 を使いました )


MkDocsのインストール

MkDocsのインストールにはpip ( Pythonのパッケージ管理システム ) が必要になります。

# pipのインストール
easy_install pip

pipをインストールした後、
下記のコマンドをターミナル上で叩くとMkDocsのインストールが開始されます。

# MkDocsのインストール
pip install mkdocs

インストールが完了すると"mkdocs"コマンドが使えるようになり、
"mkdocs new <ドキュメントのプロジェクト名>"でプロジェクトが作成されます。

# プロジェクトの作成コマンド (今回は my-docという名で作成しました)
mkdocs new my-doc


MkDocsのフォルダ構成

以下が "mkdocs new " コマンドで作成されたMkDocsのファイル群です。
ymlファイルとdocフォルダ、MarkDownファイルが1つずつ作成されるというシンプルな構成になっていますね。

- 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

* testDir/testDoc.mdファイルのページ

tabスペースを2つ追加するとプログラミングコードと見なされ、自動的にハイライトされます。

[//]: <> (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形式にビルド


Summary

MkDocsを使うとMarkDown形式で記述出来るので、
簡単に素早くドキュメント作成が出来そうです。

実際のプロジェクトで使う時も静的ファイルに変換されるので、
Webのプロジェクトではpublicフォルダ内に直接置くことも可能ですね。

次のプロジェクトではMkDocsを使ってみては如何でしょうか!

MkDocs

 

この記事のカテゴリ

プログラミング

この記事のタグ

開発ツール , Python , OSSパッケージ

Socialシェアボタン

スポンサーリンク