MkDocs 使ってみた。

Python

昨日任された業務を紹介しよう。

Web上でパワポの内容をWebページで見れるようにして！

というものだ。
こんなとき、MkDocsがとても便利。

MkDocsの公式に飛ぶ。 f:id:kimoppy126:20170708094043p:plain

サイト自体がMkDocsで作られてる。 こんなページがMarkdownでお手軽に作れるのがMkDocs。 いちよPythonのアプリだけどPythonでコーディングするわけじゃない。

インストール

動作環境

MkDocs supports Python versions 2.6, 2.7, 3.3, 3.4, 3.5 and pypy.

を満たしていればOK

pipのインストール

pipはデフォルトでインストールされているはずだが、ない場合や古い場合、インストールが必要。

  • pipをすでにインストール済みの場合。
    以下のコマンドでアップデート

    pip install --upgrade pip

  • インストールしてない場合。
    get-pip.pyをダウンロードして以下のコマンド

    python get-pip.py

MkDocsのインストール

pipを使ってMkDocsをインストールする。

pip install mkdocs

$ mkdocs --version
mkdocs, version 0.15.3

※Windowsを使っている場合

python -m pip install mkdocs
python -m mkdocs

Webページの構築

mkdocs new my-project
cd my-project

Getting started is super easy.

super easyですね。
mkdocs.ymlというconfigファイルとdocsというドキュメントのソースファイルを入れるファイルが作られます。docsにはデフォルトでindex.mdが入ってます。MkDocsはビルドインのサーバーなので、ドキュメントを作りながらWeb上でどう表示されるのか見ることができる。
mkdocs.ymlと同じディレクトリ上で、以下のコマンドを打つと、サーバーが立ち上がる。

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

適当なWebブラウザでhttp://127.0.0.1:8000/にアクセスすると、f:id:kimoppy126:20170708101048p:plain
こんな感じでデフォルトのホームページが見れる。

MkDocsはオートリロードに対応しているので、mkdocs.ymlやdocs内のファイルに変更を加えるとすぐにWeb上に反映される。

ドキュメントの追加

docs/ディレクトリに.mdファイルを追加することに加え、mkdocs.ymlを編集する必要がある。しなくても自動で読み込まれるが、アルファベット順で並べられるため、ドキュメントの順番を指定したい場合は編集する。
最上位の階層に2つのページを追加する場合、以下のように編集する。

pages:
- 'index.md'
- 'about.md'

このままではディレクトリの名前がページの名前として認識され、docs/index.mdと docs/about.mdページが追加される。

自分で指定した名前をページに与えたい場合は以下のようにする。

pages:
- Home: 'index.md'
- About: 'about.md'

階層を持った構造にしたい場合

以下のようにセクションタイトルの下に関連ページを並べれば、サブセクション構造を持ったページが作られる。

pages:
- Home: 'index.md'
- User Guide:
    - 'Writing your docs': 'user-guide/writing-your-docs.md'
    - 'Styling your docs': 'user-guide/styling-your-docs.md'
- About:
    - 'License': 'about/license.md'
    - 'Release Notes': 'about/release-notes.md'

ドキュメント中に画像やgithubのページを含めたい場合

docs/以下のディレクトリに適切に配置すればよい 例えばGithubのCNAREファイル、PNGフォーマットのscreenshot.png画像を追加したいとき、ファイルのレイアウトを以下のようにする。

mkdocs.yml
docs/
    CNAME
    index.md
    about.md
    license.md
    img/
        screenshot.png

あとはドキュメント中にマークダウン記法で書けばいいだけ。

Cupcake indexer is a snazzy new project for indexing small cakes.
![Screenshot](img/screenshot.png)
*Above: Cupcake indexer in progress*

テーマの設定

ドキュメントをどう表示させるか(サイトの見た目)を変更する場合、 mkdocs.ymlファイルを編集し、themeを設定します。

site_name: MkLorum
pages:
    - Home: index.md
    - About: about.md
theme: readthedocs

theme: readthedocsに設定すると、こんな感じ。

f:id:kimoppy126:20170708110548p:plain

ビルドインのテーマはmkdocsとreadthedocsしかないぽいけどサードパーティーにはいい感じのが結構ありそう

サードパーティーのテーマは以下から入手可能
MkDocs Themes · mkdocs/mkdocs Wiki · GitHub

テーマのカスタマイズに関しては以下を参考に
Styling Your Docs - MkDocs

Templateの利用

ある程度整ったTemplateが配布されてたりする。 Templateから作った方が、いろいろ勝手がわかりやすい。

GitHub - BPA-CSIRO-Workshops/btp-manuals-md: This contains all material for Markdown version of BTP workshops

HTMLへの出力

Markdownで作ったファイルをHTMLに出力できる。mkdocs.ymlと同じディレクトリで、

mkdocs build

これにより新しくsiteディレクトリが作られる。

$ ls site
about  fonts  index.html  license  search.html
css    img    js          mkdocs   sitemap.xml

sitemap.xml fileや mkdocs/search_index.jsonといったファイルも作られる。
gitでファイルを管理している場合、siteファイルはgitの管理下に置きたくないので、以下のコマンドで.gitignore fileに"site/"を追加する。

echo "site/" >> .gitignore

感想

絵文字が使えなかったのがとても残念だけどかなり便利。というかMarkdownが便利。

参考

www.mkdocs.org