[Sphinx] 自分用のNote, Warning的なものを作成

環境: Sphin 1.7.2

概要¶

Sphinxで便利な note , warning を拡張したものを自作する

やり方¶

要約

• admonition を利用する
• 同時に class を利用する
• class に応じたスタイルをCSSから作成する

admonition というのが実は note, warning 系のdirectiveの元 となるクラス。これを直接宣言し、コロン2つの後にタイトルをつけてやる。 これにより普段なら「注釈」などと表示される部分を自分用の宣言に変えるこ とが可能。

つまりSphinxのrstファイルに対して、以下のように宣言をする。

.. admonition:: ここにタイトルを入れる
   :class: myOwnStyle

   ここには普段通り内容を記載する

また、上記の自作admonitionの見栄えを変えたいということがあるはず。デフォ ルトだと note と同じ色になってしまうようだが、それだと紛らわしい。 そこでスタイルを変えるために上記のコードで行なっているのが、 :class: による宣言だ。

:class: で記載した英数字は全て小文字に変換された上で、HTML上の classとして要素に追加される。したがって、自分でCSSを書いてそのclassに 対するスタイルを設定してしまえばいい。

具体的にどのような要素に変換されているかは変換後のHTMLを見るとよくわか るが、以下のようになっている。

<div class="myownstyle admonition">
       <p class="first admonition-title">my title goes here</p>
       <p class="last">this is the admonition text</p>
</div>

したがって、以下のようにCSSに追加してやれば見た目も変更される。

.myownstyle .admonition-title {
  font-weight: bold;
  background-color: red;
}

ちなみに、カスタムCSSを読み込ませる方法は以下。conf.pyの最下部辺りに setup という関数を作成し、その中で読み込ませる。 add_stylesheet 関数に渡す引数はスタティックファイルが入るディレク トリからの相対パスであり、スタティックファイルを入れるディレクトリの名 前は含んではいけない。

つまり、スタティックディレクトリがデフォルトの _static で、 _static/css/my.css というパスにCSSファイルが存在するのであれば下記 の通り _static は除いた相対パスを指定する。

conf.py¶

def setup(app):
    app.add_stylesheet('css/my.css')

参考サイト: https://stackoverflow.com/a/9738992