Sphinx でドキュメントを作成する際、テーマを設定することができます。
デフォルトで用意されているテーマは一応全て試してみましたが、どれも気に入りませんでした。
なので、私はいつも Read the Docs のテーマ (sphinx_rtd_theme) を使用しています。
しかし、sphinx_rtd_theme にも気に入らない点がいくつかあります。
気に入らない点
見出しが分かりづらい
見出しのレベルによる違いが文字の大きさだけなので、どこが見出しの境目なのか分かりづらいと思います。
ちなみに Docker のドキュメントも sphinx_rtd_theme を使用していますが、こちらはカスタマイズされているようで、見出しにアンダーラインが引かれています。
これは分かりやすくなっていて良いと思います。
画面の横幅が固定されている
レスポンシブ対応のためか、sphinx_rtd_theme は PC のブラウザで閲覧したときに横幅が MAX まで広がりません。
PC でしか閲覧しないなら横幅 MAX まで広げたいところです。
テーブルにスクロールバーが表示される
レスポンシブ対応のためか、テーブルでセル内の文字数が多い場合に自動改行されず、横スクロールバーが表示されてしまいます。
こちらも PC でしか閲覧しないなら折り返して全体を表示してほしいところです。
テーブルのカラムが等幅になる
これは sphinx_rtd_theme ではなく Sphinx の仕様ですが、テーブル作成時に widths 属性を設定しなかった場合、各カラムは等幅になります。
解決方法
HTML 作成後に CSS を上書きするようにしてやります。
以下のような内容で _static/css/my_theme.css を作成します。
@import url("theme.css");
.wy-nav-content {
max-width: none;
}
h1,h2,h3,h4,h5,h6 {
border-bottom: 1px solid #ccc;
}
.wy-table-responsive table td, .wy-table-responsive table th {
white-space: normal;
}
colgroup {
display: none;
}
conf.py に以下の設定を追加します。
html_style = "css/my_theme.css"
以上で完了です。
