MkDocsを触ってみる

開発をしているときにたとえ一人であってもプロジェクトが大きくなってくると全てを管理するというのは難しくなります。そこでドキュメントが欲しい！となると思います。今回はドキュメントを生成できるツールの一つであるMkDocsについて紹介します！

インストール

mkdocs自体はpythonで作られています。ドキュメントツールというだけあって立ち上げ方も簡潔にまとめられているので特に解説はしません。ページの追加からナブバーの追加方法まで書いていてかなり親切な部類に入ると思います。立ち上げ手順のリンク

いくつかポイントを書いておきます。

• pythonを使う上で仮想環境を入れた後にインストールする事をお勧めします。venvが個人的にお勧めです。

 設定について

テーマや設定などデフォルトでは不十分なところがあるので変えていく方が良いと思います。設定は全てmkdocs.ymlの中に書いていきます。(チュートリアルを見て「mkdocs new プロジェクト名」 で初期化していることが前提です。)

テーマ

• 正直materialテーマ一択なのではと思っています。いくつかの追加機能も提供してくれていますしテーマ自体も綺麗です。

設定にもそのテーマを設定しておきましょう

theme: 
  name: material

数値の順番がおかしくなっているのを修正

なんて表現したら良いのか説明が難しいのですがデフォルトの状態でmkdocsを使っていると箇条書きをネストしようとしてもそれがうまく行われなかったり数値リストの間に改行が入ると数字がまた1からになったりまた箇条書きにしたいのに勝手に数値になったりしてしまいます。少し挙動が変わってしまうのでこれを修正していきます。

mkdocsの設定をする前にその設定のために必要なパッケージをインストールします。

pip install mdx_truly_sane_lists

次に設定に以下を追記します。

markdown_extensions:
  - mdx_truly_sane_lists:
      nested_indent: 2

以上です。これを知っているかどうかで結構変わってくるので紹介しました。

Mermaidを使えるようにする

githubにも取り入れられて書くことが一気に増えたMermaid。mkdocsでも使えるようにすることができるのでその紹介をしておきます。
と言ってもデフォルトで動くので以下の設定を追加するだけで終わります。
ドキュメントを見た感じ2022年12月の時点ではまだExperimentalの段階で今後設定が変わる可能性もあるので注意してください。

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

先ほど紹介した修正をしている場合はmarkdown_extensionsは不要です。それ以下の行をmdx_truly_sane_listsと同じ階層内に追加してください。

PlantUMLを使えるようにする

全てMermaidでということも行かないと思います。過去の遺産があったりMermaidでは不十分であったり。そういう場合にもPlantUMLを組み込むこともできます。

必要なパッケージをインストール

pip install plantuml-markdown

設定を記述

markdown_extensions:
  - plantuml_markdown:
      server: http://www.plantuml.com/plantuml

これでコードブロックをplantumlとして指定してコードを書いてください。
例としては以下のような感じです。

```plantuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
```

公式サイトより例を持ってきました。mkdocsで書く場合は@startuml, @endumlは必須ではありません。

まとめ

今回はmkdocsの設定を中心に紹介しました。mkdocsではマークダウンであればHTMLとしてレンダリングできるだけ例えばprotoc-gen-docでマークダウンをmkdocsのディレクトリ内に生成して最終的にHTMLとしてレンダリングすることも可能です。(protoc-gen-docはデフォルトでもHTMLでの出力に対応していますがこの手法によってドキュメント内にprotoのドキュメントを入れることが可能になります)

最終的にはGitHubPagesにデプロイと言ったこともできるのでみるたびにサーバーを立ち上げてと言ったことも必要ないですし元のデータがマークダウンなのでサーバーを立ち上げるまでもなくみることができます。モノレポであればドキュメントとコードを一緒にバージョン管理すると言ったこともできますしテーマも用意されているのでドキュメントの記述にのみ注力することができます。

ドキュメントツールを探している場合は入れて損はないと思うので一度試してみてください！