Sphinx、良いんじゃないですか
業務で少し関係あるので調べていました。例によって書籍を入手（直販のみで、一般の書店では購入できないとのこと）。
開発用ドキュメントを作るのは、もっぱらMarkdownだったので、reStructuredTextもなんとなく、あんまり流行っていないしちゃんと勉強するのもなーと思ってしまっていました。あとは、いま、現在使われている現場でできあがっているドキュメントの見た目がなんか好きくなくて、とにかく印象があまり良くなかったわけです。ちなみに、reStructuredTextはSphinxのために作られた記法らしい。
ところが、書籍を読んで、とあるURLを見て私の印象が変わりました。
Sphinxでできることが全部詰まっているサンプルページです。どれでもいいのでPreviewを開けましょう。サンプルは複数ページに分かれているので、ともかく全部見ましょう。表現力はさすがにMarkdownよりもはるかに上だと思います。加えて言うと、Markdownのように「標準化」の問題が存在しません。これは結構でかい。GFMもいつまでもつかわからんし、CommonMarkもどうなっているのかわからんし、少なくとも実装は2021年になってもバラバラのままです。おちつかない。コマンドラインツールとして提供されているので、プログラマには何の違和感もなく使えるわけです。
そして、そもそもですが、Sphinxには拡張機能があって、CommonMarkも使えます。見た目も機能も、エコシステムはできあがっている。こうなると疑問はただ一つ、なんで流行ってないの…？安心感パないよ…？
ちなみに、上記は個人的にいいなと思ったsphinx-materialです。マテリアルデザインっぽいのは2つありますけど、もう一つはけっこうGoogle感がつよい。他にもテーマはたくさんあるんですけど、名前にプロダクト名が入っているものは、そのプロダクト専用で使っているものを公開している感じで、ちょっと汎用的な目的には使いづらいかもしれないですね。ロゴ画像がテンプレートに埋め込まれていることも多いので。Mozilla、Ansible、Flask、Boost、Unreal Engineなど、挙げればキリがないかもしれません。
表記法を安心して使いたいのと、Tex記法もぜんぜん大丈夫そうなので、めちゃ便利かも。
気になる方はぜひぜひ。
