MkDocs
MkDocsのインストールは、
pip install mkdocsで簡単にインストールできますが、デフォルトで使えるテーマが2種類しかなく、しかもややダサい(個人的感想)気がします。したがって、インストールの際、よりスタイリッシュにカスタマイズできるmkdocs-materialも一緒にインストールすることをおすすめします。インストールが完了しましたら、
mkdocs new プロジェクト名とコマンドを打ちますと、以下のような構成のディレクトリが作成されます。
my-project/
mkdocs.yml
docs/
index.md
mkdocs.ymlというファイルはYAML形式で記述する設定ファイルです。この中にサイトの情報やその他諸々の設定を記述していきます。例えば、インストールしたテーマmkdocs-materialの反映、サイトの説明、サイトのURL、コピーライトを設定ファイルに記述すると、以下のようになります。
----------
mkdocs.yml
----------
site_name: My project
site_description: 'This is test.'
site_author: 'watasi'
site_url: 'https://foo.com'
copyright: 'Copyright © 2019 watasi'
theme:
name: 'material'
nav:
- Home: 'index.md'
mkdocs-materialの公式ページに分かりやすく書かれています。Netlify
作成したドキュメントをホスティングする方法として私が使っているサービスはNetlifyです。mkdocsには手軽にgithub pagesにデプロイできるgh-deployコマンドもありますが、私は最終的にNetlifyにしました。こちらのほうが手軽なように感じたからです。方法は簡単です。まずプロジェクト内に
runtime.txtとrequirements.txtを作成します。そしてそれぞれに以下のような記述をします。
ディレクトリ構成は
my-project/
mkdocs.yml
runtime.txt
requirements.txt
.gitignore
docs/
index.md
-----------
runtime.txt
-----------
3.6
----------------
requirements.txt
----------------
mkdocs
mkdocs-material
runtime.txtの方は、Pythonのバージョン情報です。NetlifyはデフォルトでPython2.7なので、もし作成の際に使用したバージョンが3.x系であるならば、記述する必要があります。requirements.txtは必要となるライブラリの情報です。Netlifyは、GitHub・BitBucket・GitLabのアカウントで入れます。したがって、プロジェクトを管理しているサービスでログインします。そして、デプロイする予定のリポジトリを選択し、ビルドの設定に入ります。ビルド設定の画面のスクリーンショットを取り忘れてしまいましたが、上から順にブランチは
masterビルドコマンドはmkdocs buildパブリッシュするディレクトリは/siteです。mkdocs buildによって、mkdocsはsiteディレクトリにHTMLやjsファイルを生成します。マークダウン記法で気軽に書けて、生成もデプロイも簡単なMkDocs。ぜひお試しください。
追記(2019/10/7現在)
2019/10/7時点で、NetlifyのDockerfileの内容を眺めていたところ、python3.7の記載がありました。ですので、この記事を書いた時点ではruntime.txtを3.6としていますが、おそらく3.7も大丈夫だと思われます。
追記(2020/2/16現在)
Netlifyからメールでお知らせが来ました。2020年4月14日から独自ドメインではなく、無料の「〇〇.netlify.com」を使っている場合、今後「〇〇.netlify.app」というドメインに変更されるようです。したがって、新たに公開しようとお考えの方は独自ドメインを使うか、4月14日以降にしたほうが良いかもしれません。
おまけ
つい最近見つけたPythonの入門書籍です。幼き頃読んでいたコロコロコミックの漫画「ゲームセンターあらし」のイラストでPythonの入門書が出版されておりました。あまりに懐かしすぎて、皆さんにもぜひご紹介したいと思った次第であります。ダイヤモンドより硬い出っ歯の主人公「石野あらし」くんが数々の超人級の技を披露します。そういえば、昭和の漫画やアニメは主人公がイケメンではないことが多かったし、個性的だったなぁ。