自社ドキュメントツールに置き換えた
ただのポエムです。長い上に何も中身はありません。乱文です。
時雨堂が公開しているオンラインドキュメントを 1 つを除いて自社ドキュメントツールに置き換え居ました。（残り一つも置き換え予定です)
もともと時雨堂では Sphinx という Python で書かれたドキュメントツールを長年利用してきました。Sphinx は reStructuredText (以降 rst) という軽量マークアップ言語を利用します。自分が rst に触れたのはかなり昔で、rst2html.py というツールを使ってドキュメントを出力したりしていました。
それから社会人になっても製品ドキュメントに Sphinx を採用したりと、ずっと rst を採用してきました。ただ、昨今の Markdown (以降 md) 一強になったため、Mdx を検討してみたり、Rspress のソースを読みつつ試行錯誤したり、何度も何度もドキュメントの md 化を検討してきました。
ただ結果的に、自分のドキュメントの書き心地を維持するためには md では厳しいという判断に落ち着きました。
そのため当面は Sphinx で頑張ろうと思っていたのですが、やはり Sphinx の苦しい部分も出てきます。それは検索だったり md 出力、そしてメンテナンスの不安定さです。あと何よりビルドが遅い。
また rst の formatter / linter がいまいちしっくりくるのが無いということで、ずっと悩んでいましたが、一念発起してドキュメントツールを自作することにしました。
ただ、ドキュメントツールは「金にならない」というのが現状です。さらに言うならば難易度だけ高くてメンテナンスコストも高い。つまり会社としてメリットは一切ありません。素直に md 系のドキュメントツールを使うのが一番効率がいいです。
そのため「一人プロジェクトとしてやる」という戦略をとりました。
戦略はシンプルで Sphinx 互換にすることです。理由は「メンテナンスに飽きたとき Sphinx に戻れるようにする」ためです。あとそもそも独自実装を考えるのはコスパ会わないですし、別にドキュメントツールの専門家でもなんでもないので、マネした方がいいです。
ちなみに設定ファイルは conf.py の代わりに mikan.jsonc を使うようにするというのだけまずは決めました。最終的には .mikan/settings.jsoc になりましたが、まずは設定ファイルをどうするかを決めるのは大事だと思ってます。
言語は Rust を採用しました、速度が目的になるのと Wasm 出力が必要な事を考えると一択かなと。
実装はまずは rst の CST / AST を作るところから始めました。Rowan を利用して、rst の CST を作りそこから AST を作る仕組みを作りました。
rst 全ての文法に対応するのではなく、実際に自社ドキュメントで利用している文法のみに絞りました。必要になったら後から追加すればいいだけです。
CST にしたのは Formatter / Linter を実現するためです。rst の formatter / linter はあるにはあるのですが Python ベースなので遅いのと、やはり「自分好み」が一番重要だと思っています。なので 1 から実装することにしました。
一通り CST / AST ができたら、次は CST / AST から HTML への出力です。この部分はシンプルに docutils を参考にしました。完全互換は目指さす「元々利用していた自社開発の Sphinx テーマ」っぽいデザインを出力できればよしと判断しました。
シンタックスハイライトは Shiki を採用しました。Rust で何か頑張るよりかは、Shiki によるレンダリング機能を実現した方がいいだろうと考えたからです。
検索はもともとは既存のライブラリを組み合わせて使う予定ですが、最終的には分かち書きだけ既存ライブラリを利用して、それ以外は完全に自前で実装することにしました。
分かち書きは Vaporetto を採用しました。依存が少なく軽量だったことが理由です。日本語全文検索の仕組み自体は 1 から実装しました。といっても難しい機能はなく BM25 スコアリングベースです。タイポトレランスもおまけで追加しました。
後は辞書機能を頑張るに完全に寄せました。今は LLM で辞書作成がそんなに大変ではなくなったというのがあります。
ドキュメント開発時の自動ビルドと自動更新も欲しいと思いました dev と build と preview は絶対必要です。さらに WebSocket を利用したブラウザの自動更新も実装しました。ドキュメントを修正したさいにブラウザ更新ボタンをおすのはいけてません。この辺りは全て Vite をマネしました。
mermaid 互換のレンダラーも実装しました。独自の仕組みも実装しました。シーケンス図やステート図など、必要最低限に抑えています。
Markdown 出力も今の時代必要です。そこで実装したのが rst2md です。CST があるので、そこから md を生成する仕組みを追加しました。 .md で md にアクセス出来るのは必須です。
md 出力ができるようになればあとは llms.txt と llms-full.txt の生成です。rst だとこれが難しかったのですが、md2rst のおかげで安定して出力できるようになりました。
今の時代ドキュメントは読むものではありません、検索するものでもありません、LLM に食わせるものです。
VS Code 拡張も作ってみました。シンプルな rst ビューワーです。Wasm で出力しています。
いろいろ夢を詰め込みまくったドキュメントツールですがまだまだやりたいことは沢山あります。ただ頑張りすぎても得られるものはほぼありません。
とはいえ、念願だった自前ドキュメントツールに切りかわったことで、やりたい放題できるようになりました。
より利用者に喜ばれるドキュメントツールに育てていくつもりです。