自社製品ドキュメントを自社ドキュメントツールに置き換えた
今まで時雨堂ではドキュメントツールに Python で作られた Sphinx というのを利用してきましたが、今回自社で開発したドキュメントツール Mikan に置き換えました。
Mikan はオープンソースではなくクローズドソースです。今後も公開予定はありません。
自社ドキュメントツールは自分にとって悲願みたいなものだったので、とても嬉しいです。やりたかったことを雑に書き出してみました。
- HTML 出力のみで良い
- reST を利用し続けたい
- 高速なビルド
- テーマを気軽に拡張したい
- reST の Formatter と Linter が欲しい
- miette 使ってわかりやすく
- VS Code 拡張作りたい
- reST LSP が欲しい
- reST Live Preview が欲しい
- 組み込み日本語全文検索が欲しい
- オフラインで動く日本語全文検索が欲しい
- タイポ耐性を持たせたい
- 類義語に対応したい
- 辞書機能持たせたい
- ダークモードが欲しい
- CLI での reST プレビューが欲しい
- 独自の図生成の仕組みが欲しい
- シングルページ出力機能が欲しい
- 開発サーバ機能が欲しい
- Markdown コピー機能欲しい
- URL に .md って付けたら Markdown 出力になってほしい
- WebSocket を利用したホットリロード機能
- Vite などが持ってる機能
- 使い慣れてる Rowan 軸にする
とにかく色々つまった自分が考えた最高のドキュメントツールを作りました。
雑感
だらだらと。
実際作ってみるとめちゃくちゃ大変でした。まず最初にやったのは reST のパーサーを作る事です。これは Rowan を使って CST / AST を用意しました。その後はシンプルにビルダーを作って HTML 生成。この辺りは Insta を使ってテストを書いています。
後は Sphinx が持つ :doc: や :ref: といった複数ページで利用する仕組みなどを実装していきました。ここは使う必要がある仕組みだけに絞りました。何でもかんでも対応する必要はないので最小限実装。
CST を作る事で reST フォーマッターが実現できますが、これはある程度ドキュメントができてからゆっくり対応することで後回しにしました。最優先は自社のドキュメントを Sphinx から置き換える事なので。
Sphinx から設定ファイル以外は変更せずに動く事を目的にしました。設定ファイルは conf.py から .mikan/settings.jsonc に切り替えました。mikan.jsonc も考えたんですが、色々細かい辞書ファイルなどが増えそうな事も考えると、ディレクトリにした方が良いだろうという判断です。
一通りビルド出来るところまで来たら元々自作していた Sphinx 用の時前テーマを移植しました。デザインに不満はなかったので、そのままの移植です。
そして、一番の課題である日本語全部検索に取りかかりました。Meilisearch や DuckDB-FTS を使って学んだことは「そんなに多機能なものはいらない」です。
また日本語に特化すればいいので、余計な機能はいりません。そして検索結果のチューニングを気軽にできるように「評価する仕組み」が必要なことは最低限理解していました。
そこで今回は検索エンジンは時前での実装をすることにしました。結局 Wasm 化する必要があるので、だったら最小限にするには自作するのが良いと考えたからです。
ただ、残念ながら、検索の専門家ではないので「期待する結果がでる」を最優先に実装を進めることにしました。またオンラインドキュメントは「軽いこと」が求められるので汎用辞書も採用するのをやめることにしました。結果的にはある程度満足できる検索システムができました。
その後は Mermaid 互換の文法で図を生成できる機能を実装しました。まずはシーケンス図、そのあとステート図を実装しましたが、ステート図は難しすぎたので、あまり頑張らずなんとなくわかるところで一旦撤退しました。あとはパケット図を作って最低限揃いました。
気になっていたサポートライフサイクルが画像だったので、サポートライフサイクル図も作成しました。
さて、一通り揃って Sphinx からの移行もできる質にはなったので公開した次第です。
大変でしたが、とても楽しく開発できました。今後もよりよいドキュメントツールを目指して継続的に開発していこうと思います。
ちなみにツール名は社員が付けてくれました。蜜柑色からとって Mikan です。