1年ぶりのnote更新になります。Sphinx用のテーマを作っています。公開するにはもう少し手直しが必要ですが、完成が遠そうなので、現時点の成果を紹介することにしました。1→10のうち、今は7-9くらいだと思っていますが、ここからが長く辛いのです。

製品を買うと取扱説明書が必ずついてくるように、プロダクトとドキュメントはセットで存在しています。それは開発者向けの計画書や設計書についても同様で、プロダクトの品質(特にソフトウェア)はドキュメントの品質に依存すると考えても過言ではありません。

そのようなドキュメントを作るには、読みやすく、書きやすく、直しやすい文書プラットフォームが必要です。これまで理想的なドキュメンテーションツールを求め、機会があれば様々なツールを試してきたのですが、最終的にSphinxに戻ってきました。

Sphinxはドキュメント作成ツールとして超有名で、私も真っ先に試したツールの一つでした。しかし、(1) rst構文を覚えないと書けない (2) 見出しの閲覧性がイマイチで、文書構造の全体像が掴みづらい (3) 高機能なので扱いが難しい ... ということで、もっと気軽に生成できる方が文書作成に専念できるはずだと考えていました。

ただし色々試した結果、とりあえずSphinxを使っておけば間違いないという結論に至りました。ユーザーが多く、高品質なdocx/tex/pdfを簡単に出力できるツールとしては唯一ではないかと思います。markdown(html)は簡単ですが、最終品質がスケールしません。c,c++,c#をよく使うのでAPI仕様書とドキュメントの両方を生成できるDoxygenが好きだったのですが、tex形式がpng画像を扱えない点が致命的でした。まあ、html出力で許される世界なら良かったのですがね。

この決断がすんなりできたもう一つの理由が、とあるモダンテーマの存在です。HTMLベースのドキュメントツールは総じて見出しの閲覧性が低く、Microsoft Wordの方が文書構造の把握と検索がし易く、HTMLベースの文書を採用する障害になっていました。しかし、furo, pydata_sphinx_theme, sphinx_book_themeのテーマは見出しを折りたたむ仕組みを実装しており、十分読みやすいと感じました。ただし、余計な機能が多く、もっとシンプルできちんと動くものを使いたかったので、これらを参考に(というか拝借して...)自前のテーマを作った次第です。

現時点では完成されているテーマを使った方がいいと思いますが、オフライン環境でも使え、手っ取り早く使える、日本語対応の保守的なテーマになれたら、と思います。

そんな気持ちで1週間くらい費やして7割くらいの完成度にもっていきました。cssが本当に辛いです。スクロールバーが変な位置に表示されたり、印刷画面で文字が見切れたり。はあ、つら。