【Sphinx】テーマ「Cloud」を手直しして使う

14340 ワード
Cygwin Sphinx cloud_sptheme Cygwin テキストリンク

1．はじめに

Sphinxのテーマとして利用者が多そうな印象がある sphinx_rtd_themeですが、数式の引用（ .. math:: の :label: オプション）を使うと、ちょっとアレな場所に表示されます。数式を使う私と相性が悪いです。

「何かないかなぁ…」と思いつつ Sphinx Themes Gallery を眺めて見つけたのが、 「 Cloud 」というテーマ。H3以下の見出しがイケてないので、これを手直して使うことにしました。ついでに .. note::, .. tip:: もちょっと変更。

２．Cloudの印象

こんな見た目です。

■アクセスすると、こんな風に表示されます

■左メニューで項目を選ぶ

選択した見出しをハイライト表示します。

一瞬で表示されるのではなく目的箇所までスクロールします。今見てる場所から上と下のどちらにあるのかわかるのは意外と便利です。

■サイドメニューの非表示

２．作業概要

  1. sphinxテーマ「cloud」のインストール
  2. h3,h4のスタイルの変更
  3. 日本語メッセージの変更

３．環境

  • Windows10/cygwin
  • Python 3.8.10
  • Sphinx 4.1.2
  • cloud-sptheme 1.10.1

４．作業内容

４．１．テーマのインストール

(1) インストールコマンド

$ pip install cloud-sptheme

(2) source/conf.py に追記する設定

html_theme = 'cloud'

４．２．h3, h4のスタイルの変更

(1) 次の内容を SPHINX_PROJECT/source/_static/my.css に保存

@import url("cloud.css");
div.body h3 {
        /*font-size: 1.525em;*/
        background-color: #A7D0DE;
        padding: 0px 10px;
        line-height: 1.4em;
        border: 1px solid rgba(0,0,0,.125);
        border-width: 0 18px 0 9px;
        border-radius: 5px
}
div.body h3.highlighted {
        /*font-size: 1.525em;*/
        background-color: #F8E196;
        padding: 0px 14px;
        line-height: 1.4em;
        border: 1px solid rgba(0,0,0,.125);
        border-width: 0 18px 0 9px;
        border-radius: 10px
}
div.body h4 {
        background-color: #E0E0E0;
        padding: 2px 10px;
        border: 1px solid rgba(0,0,0,.125);
        border-width: 0 36px 0 18px;
        border-radius: 5px
}
div.body h4.highlighted {
        background-color: #F8E196;
        padding: 2px 10px;
        border: 1px solid rgba(0,0,0,.125);
        border-width: 0 36px 0 18px;
        border-radius: 10px
}
div.body h5 {
        background-color: #E0E0E0;
        padding: 0px 10px;
        border: 1px solid rgba(0,0,0,.0625);
        border-width: 0 72px 0 36px;
        border-radius: 15px
}
div.body h5.highlighted {
        background-color: #F8E196;
        padding: 0px 10px;
        border: 1px solid rgba(0,0,0,.0625);
        border-width: 0 72px 0 36px;
        border-radius: 15px
}
div.body h6 {
        background-color: #E8E8E8;
        padding: 0px 10px;
        border: 1px solid rgba(0,0,0,.0625);
        border-width: 0 144px 0 72px;
        border-radius: 20px
}
div.body h6.highlighted {
        background-color: #F8E196;
        padding: 0px 10px;
        border: 1px solid rgba(0,0,0,.0625);
        border-width: 0 144px 0 72px;
        border-radius: 20px
}

(2) source/conf.py に次の設定を追記。 

html_style = 'my.css'
html_static_path = ['_static']

html_static_path は通常は上記の内容で記載済み。

(3) 次のような見た目になります。H3の色味がイケてないので、誰か提案して。。

４．３．日本語メッセージの変更

(1) 次のディレクトリがある確認して、無ければ作成する。

/usr/local/share/locale/ja/LC_MESSAGES

(2) 次のディレクトリにある３つの sphinx.* を上記のディレクトリにコピーする。 /usr/local/lib/python3.8 は環境により異なります。

/usr/local/lib/python3.8/site-packages/sphinx/locale/ja/LC_MESSAGES/

(3) sphinx.po を編集する。今回変更したのは次の通り（diff）

--- /usr/local/lib/python3.8/site-packages/sphinx/locale/ja/LC_MESSAGES/sphinx.po       2021-08-23 09:53:39.864320200 +0900
+++ /usr/local/share/locale/ja/LC_MESSAGES/sphinx.po    2021-08-24 15:28:15.887788100 +0900
@@ -3119,15 +3119,15 @@

 #: sphinx/locale/__init__.py:258
 msgid "Note"
-msgstr "注釈"
+msgstr "メモ"

 #: sphinx/locale/__init__.py:259
 msgid "See also"
-msgstr "参考"
+msgstr "見てね"

 #: sphinx/locale/__init__.py:260
 msgid "Tip"
-msgstr "ちなみに"
+msgstr "TIP"

 #: sphinx/locale/__init__.py:261
 msgid "Warning"

(4) source/conf.py に次の設定を追加。 language は設定済みのはず。

language = 'ja'
locale_dirs = [
    '/usr/local/share/locale',
]

以上