はじめに
うるせェ!!! 行こう!!!!、nikkieです。
Sphinxに関する小ネタです。
ビルドしたHTMLに取り消し線1を引く方法を共有します。
目次
- はじめに
- 目次
- 結論:Sphinxで出力するHTMLに取り消し線を引く方法2つ
- 1. ライブラリ sphinxnotes-strike
- 2. Sphinxで出力するHTMLに取り消し線を引けるように設定追加する
- 2がこんなに簡単な秘密はdocutilsに
- 2の使用例(sphinx-revealjs)
- 終わりに
結論:Sphinxで出力するHTMLに取り消し線を引く方法2つ
- ライブラリ
sphinxnotes-strike
を使う - 少しの設定追加で、簡単に自作もできます
- 触るのはreSTとCSSファイルだけです
- この記事では2を中心に扱います
1. ライブラリ sphinxnotes-strike
このライブラリはHTMLだけでなくLaTeXもサポート2しているそうです。
私は2の方法で自作していて、このライブラリは存在を知ったばかりです。
ドキュメントによると、インストールした後はconf.py
のextensions
に加えるだけ!3
すごく簡単に使えそう4ですので、「これいいじゃん!」と思った方は試してみてください。
2. Sphinxで出力するHTMLに取り消し線を引けるように設定追加する
User Groupに「取り消し線を引きたい」という項目があります。
こちらの通りで
- reSTでロールを追加
- CSSを追加
これだけで取り消し線が引けるようになるんです!
例としてreSTではstrike
ロール5を追加します(a)。
.. role:: strike
CSSも追加します(b)。
.strike { text-decoration: line-through; }
この後は、reSTで strike
ロールが有効になります!
:strike:`うるせェ!!! 行こう!!!!`
2がこんなに簡単な秘密はdocutils
に
こんなに簡単とは思ってもみなかったので、どんな仕組みなのか少し調べてみました。
ポイントはrole
ディレクティブです。
https://docutils.sourceforge.io/docs/ref/rst/directives.html#custom-interpreted-text-roles
The "role" directive dynamically creates a custom interpreted text role and registers it with the parser.
nikkie訳: role
ディレクティブは、カスタマイズしたinterpreted text role(解釈されたテキストロール)を動的に作り、それをパーサに登録します
ドキュメントの例が分かりやすく、
.. role:: custom
と定義したcustom
ロール。
これを
An example of using :custom:`interpreted text`
と使うと、ドキュメントを表す木としては
<paragraph> An example of using <inline classes="custom"> interpreted text
となる、つまり、customクラスが付与されています!
これをstrike
ロールに読み替えると、先の例の「うるせェ!!! 行こう!!!!」には、HTMLでstrike
クラスが付与されることになります。
追加したCSSによりstrike
クラスにはtext-decoration: line-through;
とスタイル設定されていますから、HTMLを表示すると取り消し線が引かれます。
role
ディレクティブで追加したロールと同名のクラスが付与されるということを活用しているんですね!
2の使用例(sphinx-revealjs
)
紹介した方法はSphinxだけでなく、sphinx-revealjs
でも使えます。
PyCon JP 2022のスライドに忍ばせた取り消し線、これはここで紹介した方法で引きました!
.. role:: strike
* :strike:`うるせェ!!! 行こう!!!!`
.strike { text-decoration: line-through; }
終わりに
Sphinxで出力するHTMLに取り消し線を引く方法を2つ紹介しました。
どちらの方法も非常に簡単です。
私は中身を知った上でうまく使うことに興味があるので2推しですが、1のライブラリに任せるのも全然ありだと思います。
ラクラク取り消し線を引いて enjoy documentation!!
- 打ち消し線ともいうかもしれません。この記事では同じものです↩
- Change Log 1.1より。https://sphinx.silverrainz.me/strike/#id2↩
- https://sphinx.silverrainz.me/strike/#installation↩
-
自作のSphinx拡張も「簡単に使える」にこだわったので、同じくらい簡単に使えそうな
sphinxnotes-strike
、よさそうに見えますね↩ - 他とも揃える前提であれば、別の名前にしてもいいでしょう↩