はじめに
今までWordでパッケージソフトのドキュメントを作成し管理していたのですが、管理が割と面倒でした。
そんな面倒なWordのドキュメント管理から抜け出す方法を模索したので、その方法を残しておきます。
あまり日本語の情報が見当たらず意外と苦労したので参考になると幸いです。
MkDocs
Markdownで書けてhtmlを自動生成してくれてオンラインでみれるURLを発行してくれるものがないかさがしていたらMkDocsに出会いました。静的サイトジェネレータです。他にもHugoとかもありますよね。
MkDocs
テーマが色々と選べますが、Read the Docsを使用する場合、テーマはreadthedocsとmkdocsの２つのみしか使用できなかったので注意です。個人的にはmaterialがカッコイイ
MkDocs使い方
以下の記事を参考にすればすぐに作成できます。
MkDocsによるドキュメント作成
MkDocs 使ってみた。
MkDocs：インストールから github pages へのデプロイまで
Read the Docs
古いバージョンを使っている人が古いマニュアル見る需要は普通にあるとおもいます。
しかし残念ながら、MkDocsだけではバージョン管理が出来ませんでした。
そしてバージョン管理できるものを探していたらRead the Docsに出会いました。
Read the Docs
Read the Docsでバージョン管理の方法
まずはこちらを参考に作成したmkdocsのリポジトリをインポートしてビルドします。
バージョン管理方法は、gitでタグ付けしてバージョン管理を行います。
gitでタグ付けしたコミットをpushすれば、自動的にRead the Docsでバージョンが別れた状態でデプロイされます。
各バージョンのドキュメントにURLが発行されて、参照することが可能になります。
gitのタグでバージョン管理するのは初めてやったので、ここが少し不安。。
ハマった点
- Read the Docsでサポートされるmkdocsのテーマはreadthedocsとmkdocsの２つのみ。最初はmaterialで作っていたので、泣く泣くreadthedocsに変更しました。materialかっこよかった。。
- 無料のRead the Docsでビルド出来るリポジトリはパブリックのみ。プライベートの場合は、Read the Docs for businessを使う必要があります。Basicプランで$50 per monthかかるみたいですね。
- 最初にRead the Docsでリポジトリをインポートしてビルドする際に次のエラーが発生し、ビルドが失敗。
Read-the-docs build fails with “cannot import name 'PackageFinder' from 'pip._internal.indexこのstackoverflowの通りにプロジェクトをwipeした後に、再ビルドしたら解決。gitのissuesにもあがってます。Latest pip release fails #6554
終わりに
静的サイトジェネレータって色々あって面白いですね。
どれがどんな用途に適しているのか、色々と模索していきたいです。
とりあえず、hugoのacademicはカッコイイから使ってみたい。