時雨堂ではドキュメントツールに Sphinx を採用しており、reStructuredText (以降 reST) を利用している。流れ的に Markdown (以降 MD) 一択という感じだが、オンラインドキュメントを書く場合には自分は結局 reST から逃げられなかった。

MD への移行を見据えて色々とドキュメントツールを試したり、作ったりしてきたがうまくいかなかった。

そこで、腰を据えて Sphinx の「利用している機能」だけを採用した、自社専用ドキュメントツールを作る事にした。

まとめ

Sphinx から移行することが無事できそうなところまできた。ツール名は Mikan (蜜柑) 。

• mikan init で .mikan/settings.jsonc を生成
• mikan build で HTML 出力
  • mikan preview で簡易ウェブサーバー
• mikan dev で開発サーバー
  • reST 変更検知対応
  • ビルドキャッシュ対応
  • ブラウザホットリロード対応
• mikan fmt でフォーマッター
• mikan lint でリンター
• mikan build 時に自動インデックス作成で日本語全文検索機能組み込み
  • 自社ドキュメントでインデックス作成は 500 ミリ秒くらい
• mikan spam.rst でターミナルプレビュー

Sphinx ドキュメント自体は変更せずに使えるようにした。ただ設定ファイルだけは新規で必要。.mikan ディレクトリに設定ファイルなどを追加できる。

作るまでに考えたことなど。雑記。

ドキュメントツールへの要求

ドキュメントツールの自分の中でどんなものがほしいのかをざっくり書き出してみた。

静的ページ

ビルドしたら後は S3 互換オブジェクトストレージやら CDN にアップロードして終わりという SSG (Static Site Generation) 機能が大前提になる。

フォーマッター

Sphinx を使っていて不満に思っていたのが、フォーマッター。reST 対応のフォーマッターが欲しい、あるにはあるのだがしっくりこない。あと Python なので遅い。フォーマッターの恩恵は本当に大きい。

リンター

現時点ではあくまで reST 的な文法に対するリンター。日本語への Linter も簡易的なものであれば実装したいところ。reST は比較的自由な文法なので、キチキチにできるような仕組みは実現したい。

開発サーバー

Sphinx にも auto-build 的な拡張があるがコレは内蔵してしまいたい。dev サーバーとして reST ファイルの変更検出はもちろん、ブラウザーのホットリローデッドも WebSocket 利用して実現したい。ビルドキャッシュも欲しい。

オフライン全文検索

検索機能はずっと課題で、今は Meilisearch を立てているがドキュメントにそんなに必要か？というのがずっとあり、シンプルな検索の仕組みを追加したい。ビルド時にインデックスを毎回構築したとしても、ドキュメントサイズが大きくなければ問題無いと考えている。

マークダウン出力機能

コピー MD ボタンがないともうドキュメントとしては許されなくなっているという認識。そのため reST から MD に変換する仕組みも必要。

VS Code 拡張

ドキュメント書く時は VS Code で書くので自動でフォーマット書けてほしいし、LSP でエラーも表示してほしいので、 VS Code 拡張は提供したい。

reST ターミナルプレビュー

気軽に確認したいときに欲しい。 :ref: や :doc: も使えるようにしたい。

検索品質評価機能

検索サーバーを扱ってて１番こまったのが「期待した結果が検索結果としてでてこないこと」なので、これを気軽に評価できる仕組みが欲しい。

依存は最小限

依存はできるだけ最小限にする。