nikkie-ftnextの日記

イベントレポートや読書メモを発信

Sphinxのテーマを素振り 〜強調した文字の色を変えてみる篇〜

Sphinx

はじめに

エミリーちゃんのことますます すきすきになりました、nikkieです😭

ドキュメンテーションツールSphinx1にはテーマという機能がありますが2、自作できると知り手を動かしました。

目次

Sphinxのテーマを作る

Sphinx-Users.jp にズバリなページがあります。

Sphinxはテーマという形で、ドキュメントの見た目を変更することができます。

ここに沿って、ドキュメントの見た目を変えていきます。
練習用の例なので、強調した文字の色を変えることにします。

強調箇所の色を変えるテーマを自作する

Sphinxのテーマに必要なものは3つ
https://sphinx-users.jp/cookbook/makingwebsite/prepare.html#id2

色を変えるにはCSSだけあればいいので、今回はHTMLテンプレートは後回しにしています

_themes下に配置

https://sphinx-users.jp/cookbook/makingwebsite/application.html#html-theme-path に沿って手を動かしました。

conf.py

html_theme_path = ["_themes"]
html_theme = 'my_custom_theme'  # sphinx-quickstartしていたらAlabasterから変える

.
├── build/
├── source/
│   ├── _static/
│   ├── _templates/
│   ├── _themes/
│   │   └── my_custom_theme/
│   │       ├── static/
│   │       │   └── custom.css
│   │       └── theme.conf
│   ├── conf.py
│   └── index.rst
└── Makefile

theme.conf

[theme]
inherit = basic
stylesheet = custom.css

https://sphinx-users.jp/cookbook/makingwebsite/conf.html#theme より

  • inheritでbasicテーマを継承することを指定
  • stylesheetに参照するCSS 1ファイルだけを指定

static/custom.css

strong {
    color: #554171;
}

自作テーマを当てた結果

強調のマークアップ箇所を用意します

hoge **foo** fuga

HTMLをビルドすると

強調したfooに色がついています！
basicテーマは非常に質素なんですね。

終わりに

Sphinxのテーマを素振りして概念を掴みました。
Alabasterなどなど、日頃からお世話になっているテーマの偉大さが自作して初めて分かります。

今回素振りしたSphinxプロジェクトの全体像はこちらから確認できます。

  1. このブログにはSphinxカテゴリがあります↩
  2. よく使うテーマはAlabasterです ↩