admonitionのサンプル¶
デフォルトの設定のままだと、admonitionのhtml/pdf出力共に味気ない。 cssとstyファイルを書いて、少しだけ見た目を改善した。
html出力の設定¶
conf.pyの末尾に以下を設定して、cssを適当にいじる。
# HTMLテーマに独自のCSS/JSファイルを読み込ませてデザイン調整等したい
# http://sphinx-users.jp/reverse-dict/html/custom-css-js.html
def setup(app):
app.add_stylesheet('custom.css') # ここはhtml用
画像ファイルや、cssは_staticディレクトリ直下へ配置する。
_staticにcustom.cssを配置
.
|-- Makefile
`-- source
|-- _static
| |-- Caution.png <--- これらは、アイコン用の画像
| |-- Danger.png
| |-- Note.png
| |-- Question.png
| |-- Tip.png
| |-- Warning.png
| `-- custom.css <--- カスタムcss
|-- _templates
|-- admonition.rst
|-- conf.py
`-- index.rst
Tip
treeコマンドの出力をそのまま使うと、pdf出力で文字化けしてしまった。 tree --charset=C とオプションを指定することで、文字化けしない文字だけで構成することで回避できる。
custom.cssでは、以下のようになっている。
/* -- div.admonition ------------------------------------------------------ */
/*アイコンの下に付くように、タイトル文の表示位置の設定*/
div.admonition p.admonition-title {
width: 65px;
padding-top: 65px;
text-align: center;
font-weight: bolder;
font-size: 18px;
float:left;
margin-left: -18px;
}
/*タイトル以外の文をアイコンを避けるように配置*/
p.last {
padding-top: 0px;
padding-right: 9px;
padding-left: 100px;
text-align: left;
margin-top: 0px;
}
/*アイコンの配置と背景色の設定*/
div.caution{
background: url(Caution.png) no-repeat;
background-position: 9px 9px;
background-size:64px 64px;
border-radius: 10px 10px 10px 10px;
background-color: #ededed;
min-height: 110px;
border: none;
}
.
.
.
pdf出力の設定¶
カスタム設定をまとめる、*.styファイルを作り、読み込ませる。
_staticにcustom.styを配置
.
|-- Makefile
`-- source
|-- _static
| |-- Caution.png
| |-- Danger.png
| |-- Note.png
| |-- Question.png
| |-- Tip.png
| |-- Warning.png
| |-- custom.css
| `-- custom.sty <--- カスタムsty
|-- _templates
|-- admonition.rst
|-- conf.py
`-- index.rst
_static/custom.styとアイコン群ををconf.pyのlatex_additional_filesを使って、build時にlatexが読み込める位置コピーさせる。 conf.pyに以下の設定を書き足す。
# preambleに長々と書きたく無いので、custom.styへ外出ししたものを読み込むようにする。
latex_additional_files = ['_static/custom.sty',
'_static/Caution.png', # admonitionで使用するアイコン画像群
'_static/Danger.png',
'_static/Note.png',
'_static/Question.png',
'_static/Tip.png',
'_static/Warning.png'
]
custom.styを読み込むために、latex_elements/preambleに設定。 passoptionstopackagesを追加しているが自分はよくわかっていない。おそらく、tcolorboxがxcolorを要求するのだと思っている。 conf.pyに以下の設定を書き足す。
latex_elements = {
.
.
.
.
'passoptionstopackages': r'\PassOptionsToPackage{dvipdfmx}{xcolor}',
# 同じディレクトリにあるcustum.styを読み込む。
'preamble': r'\usepackage{custom}',
}
custom.styでは、admonitionのマクロの置き換えを行なっている。
- 灰色の囲いは、tcolorboxパッケージを使って描画している
- admonitionのマクロは、sphinx.styの中で定義されている以下のマクロを再定義して、実装している。
- cautionはsphinxcautionマクロ、dangeはsphinxdangerが定義されている。
\usepackage{tcolorbox}
% sphinxadmonitionを一部上書きするためのHelperマクロ。アイコンと文字列を指定して囲みを作る。
\newenvironment{sphinxadmonition_helper}[2] % アイコン画像名, タイトル文字列
{
\begin{tcolorbox}[colframe=white ,sidebyside, lower separated=false, lefthand width=1.6cm, arc=5mm]
\center
\includegraphics[width=1.6cm]{#1}\\
\bf #2
\tcblower
}
{
\end{tcolorbox}
}
% ".. caution::"の対応。sphinx.styのsphinxadmonitionの中から呼び出されるマクロを上書きしている
\renewenvironment{sphinxcaution}[1]
{\begin{sphinxadmonition_helper}{Caution.png}{#1}}{\end{sphinxadmonition_helper}}
% ".. danger::"の対応。
\renewenvironment{sphinxdanger}[1]
{\begin{sphinxadmonition_helper}{Danger.png}{#1}}{\end{sphinxadmonition_helper}}
.
.
.
以下サンプル¶
Caution
caution用のディレクティブはこう。old mac風のアイコンで区別できるようにしてみてます。なかなかにそれっぽくできた。
Danger
危険(?)のディレクティブをかくとこんな感じ。前回は爆弾マークだったのだが、テロ推奨マークのようであまりいい感じがしなかったので、ドクロマークに変更した。
Note
ノート用のディレクティブはこう。この”Note”や”Danger”の文字を消すには、コラムディレクティブ(http://sphinx-users.jp/cookbook/columndirective/index.html)を使う必要があるみたい。CSSのfloat属性とPaddingをうまく使って、”Note”や”Danger”の文字をアイコンの下へつけるようにした。
Tip
tipのディレクティブをかくとこんな感じ。本文の上辺のpaddingもアイコンの上辺と合わせたつもり。
Warning
警告用のディレクティブをかくとこんな感じ。種類によって背景色も変えた方が良いかもと思って色々と試した。が、色をつけると以外に下品になる。色についてはAppleHelpFileを作るときにもう少し考えてから行うことにする。