nikkie-ftnextの日記

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

Sphinxで出力するHTMLに取り消し線を引きたい

Sphinx

はじめに

うるせェ！！！ 行こう！！！！、nikkieです。

Sphinxに関する小ネタです。
ビルドしたHTMLに取り消し線1を引く方法を共有します。

目次

結論：Sphinxで出力するHTMLに取り消し線を引く方法2つ

  1. ライブラリ sphinxnotes-strike を使う
  2. 少しの設定追加で、簡単に自作もできます
    • 触るのはreSTとCSSファイルだけです
    • この記事では2を中心に扱います

1. ライブラリ sphinxnotes-strike

このライブラリはHTMLだけでなくLaTeXもサポート2しているそうです。

私は2の方法で自作していて、このライブラリは存在を知ったばかりです。
ドキュメントによると、インストールした後はconf.pyのextensionsに加えるだけ！3
すごく簡単に使えそう4ですので、「これいいじゃん！」と思った方は試してみてください。

2. Sphinxで出力するHTMLに取り消し線を引けるように設定追加する

User Groupに「取り消し線を引きたい」という項目があります。

こちらの通りで

  1. reSTでロールを追加
  2. 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のスライドに忍ばせた取り消し線、これはここで紹介した方法で引きました！

https://github.com/ftnext/2022_slides/blob/d081237c6c3d2cd514fca92a547ba65bc033c4f3/source/pyconjp/python_and_star.rst#L9

.. role:: strike

https://github.com/ftnext/2022_slides/blob/d081237c6c3d2cd514fca92a547ba65bc033c4f3/source/pyconjp/talk_introduction.rst.txt#L19

* :strike:`うるせェ！！！ 行こう！！！！`

https://github.com/ftnext/2022_slides/blob/d081237c6c3d2cd514fca92a547ba65bc033c4f3/source/_static/css/common.css#L14-L16

.strike {
  text-decoration: line-through;
}

終わりに

Sphinxで出力するHTMLに取り消し線を引く方法を2つ紹介しました。

  1. ライブラリsphinxnotes-strike（LaTeXも対応）
  2. roleディレクティブとCSS追加で、簡単に自作できる

どちらの方法も非常に簡単です。
私は中身を知った上でうまく使うことに興味があるので2推しですが、1のライブラリに任せるのも全然ありだと思います。

ラクラク取り消し線を引いて enjoy documentation!!

  1. 打ち消し線ともいうかもしれません。この記事では同じものです↩
  2. Change Log 1.1より。https://sphinx.silverrainz.me/strike/#id2↩
  3. https://sphinx.silverrainz.me/strike/#installation↩
  4. 自作のSphinx拡張も「簡単に使える」にこだわったので、同じくらい簡単に使えそうなsphinxnotes-strike、よさそうに見えますね↩
  5. 他とも揃える前提であれば、別の名前にしてもいいでしょう↩