脱 Sphinx (reStructuredText)

まとめ

• 当面は Sphinx で行く
• Sphinx + reStructuredText + Meilisearch を超える組み合わせが見つからない

モチベーション

• Sphinx と reStructuredText は一般的ではない
  • 便利だし、慣れている
  • ただしカスタマイズには手間がかかる
  • 独自テーマを開発して運用している
    • https://github.com/shiguredo/sphinx_shiguredo_theme
  • 自動ビルドツール
    • sphinx-autobuild · PyPI
    • sphinx-doc/sphinx-autobuild: Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.
• 結局 Markdown の一人勝ち
  • 世は md/mdx 時代
• GitHub Copilot Enterprise は md/mdx に優しい
• 日本語全文検索は入れたい、そうなるとコンポーネント化できる MDX は強い
• MDX (JSX) で好き放題できるのは良い
• Meilisearch のドキュメントが MDX でできていて、スクレイピングと相性良さそう
  • https://github.com/meilisearch/documentation

脳内ダンプ

• 結局 MDX で自分たちにとって便利なドキュメントツールを作るのが一番いいのではないか？
  • なにか機能が欲しいときはコンポーネントを開発すればいい
• Sphinx は多機能すぎる
  • 便利ではあるが、そこまで使い込んでいるわけではない
• MDX を採用する
  • https://mdxjs.com/
• レンダリングツール
  • Astro が無難そうだが他にあるのか？
• そのうち mdx-rs みたいなのが出てきて高速レンダリングに対応しそう
• rst で使っていた文法をコンポーネントとして取り込むことで上手く取り入れられそう
• 全文検索は絶対入れたい
  • Meilisearch で良い
  • Meilisearch Cloud を採用してもいいかもしれない

Sphinx + Markdown という戦略

正直あまり取りたくない ... 。

mdBook

• https://github.com/rust-lang/mdBook
  • Rust で書かれており Rust で利用されいる markdown 向けのドキュメントツール
• 全文検索が日本語に対応していない
  • https://blog.bridgey.dev/2023/06/14/search-japanese-on-mdbook/
  • 頑張ればできそうな話も出てる
• 仕組み自体はとても良くできている
• デザインは自前で用意した方がいい気がする