nikkie-ftnextの日記

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

SphinxはreSTのロールをピンポイントで使ってスタイルを整えられる！全部2連バッククォートにしていた過去の私に伝えたい多様なロール

Sphinx

はじめに

がんばったのに…な…1、nikkieです😭

Sphinxのロール、これは本当に多様なんです！
コード片もコマンドもファイルパスも全部2連バッククォートでマークアップしていましたが、より適切なロールを使ってスタイルを整えられるのです。

目次

Sphinxのロール

Sphinxの原稿としてreST（reStructuredText）を書いている前提です。

ロールは以下のように書かれます2。

:rolename:`content`

『Sphinxをはじめよう』🐊に分かりやすい説明がありました（付録A）。

ロールは、対象のテキストに装飾、関連付け、リンクといった処理を行います。

ロールはコロン文字1つで囲まれ、対象テキストはバッククォート文字1つで囲まれます。

rolenameというロールはコロンで囲まれていますし（:rolename:）、対象テキスト（content）はバッククォートで囲まれていますね！

2連バッククォートによるマークアップ

私はこれまで、コード片もコマンドもファイルパスも地の文と区別するためにすべて2連バッククォートで囲んできました。

では ``cd`` コマンドでワーキングディレクトリを移動しましょう。

エディタで ``example.py`` を開いてください。

``print("さかなー")`` という関数呼び出しは・・・

『Sphinxをはじめよう』によると、2連バッククォートは「コードなどを表現するインラインリテラル記法」と解説されます（A.1）。
また、ロールを使ったインライン記法（A.2）として、literalロールも紹介されます。

docutilsのドキュメントを参照すると、2連バッククォートとliteralロールは基本的に同じものと考えてよさそうです。

https://docutils.sourceforge.io/docs/ref/rst/roles.html#literal

「These are equivalent」（同じもの）と例示されています3。

``text``
:literal:`text`

ピンポイントで使えるロールを紹介！

Sphinxのロールのドキュメントには、「上記以外の意味のマークアップ」という項目があります。

以下のロールは、テキストのスタイルを変更する以外には特別なことはしません。

この後に続くロールを知ったことで、先の全て2連バッククォートの例を私は以下のように変えて書いています：

では :command:`cd` コマンドでワーキングディレクトリを移動しましょう。

エディタで :file:`example.py` を開いてください。

``print("さかなー")`` という関数呼び出しは・・・（※後述）

これで全部2連バッククォートよりもさらにいい感じにスタイルが変わるんです！

:command:

rm のような、OSレベルのコマンドの名前に使用します。

:file:

ファイルやディレクトリの名前に使用します。

fileという名のロールですが、ディレクトリにも使っています。
ファイルパス用のロールという理解です。

なお、ドキュメントには変数も使えると案内されます。

:guilabel:

インタラクティブなユーザインタフェースの一部のラベルとして表示される文字に対しては guilabel を使用します。

:kbd:

キーボード操作のキーに使用します。

:kbd:`Control-x Control-f`

こんなロールまで！使っていきたいロール

改めてドキュメントを見て「こんなのあったんだ！今度使ってみよう」というロールを書き出していきます。
ここに紹介した以外にもありますので、興味を持たれた方はぜひロールのドキュメントを覗いてみてください。

:code:

インラインコード用のロールです。
この記事を書くにあたって調べるまで、インラインコードこそ2連バッククォートだと勘違いしていました（何も分かっていなかったんだな…）

:code:`print("さかなー")`

シンタックスハイライトはしないそうですが、ドキュメントにはroleディレクティブを用いてシンタックスハイライトするロールを作る方法が紹介されていますよ。
これは是非試したいぞ！

:abbr:

言葉の短縮形を書くのに使用します。

HTMLではツールチップとして使用され、LaTeXでは一度だけ出力されます。

メニュー選択は menuselection ロールを使用すべきです。
これはメニュー操作の手順をマークアップするのに使用します。

:menuselection:`Start --> Programs`

:program:

実行プログラムの名前です。

:regexp:

正規表現です。

:samp:

リテラルのテキストの一部です。

:pep:

Python拡張提案書(PEP)への参照です。

:rfc:

インターネットのRFCへの参照です。

PEPやRFCへリンクが作れるんですね！

使用例（sphinx-revealjs含む）

2つ紹介します。

1つ目は自作したsphinx-new-tab-linkのドキュメントから4：

あなたのSphinxプロジェクトの :file:`conf.py` でこの拡張を有効にしてください。

もう1つ5、今回紹介したロールはsphinx-revealjsでも使えます！6

e.g. Lexical analysis (:command:`python -m tokenize -e mario.py`)
--------------------------------------------------------------------------------

:command:ロールはstrong（強調）になります。
スライドではカスタムCSSで強調箇所の色を緑色に変えているので、コマンドが緑で表示されています。

終わりに

Sphinxの多様なロールを紹介しました。
過去の私は全部2連バッククォート（インラインリテラル記法）を貫いていましたが、多様なロールの存在を知り、:file:や:command:など使い始めています。
これらは2連バッククォートと比べてスタイルが変わるのがよくて、手放せなくなりました。
まだ全部触れているわけではないので、今後触っていくのが楽しみです！

reSTを書くときに「ここ、2連バッククォートよりもスタイルをいい感じにできるマークアップがあるかも」と思ったら、ちょっと手間かもしれませんが、ロールのドキュメントを見てみてください。
きっとreST（ひいてはSphinx）をさらに使いこなすきっかけになると思いますよー！

Sphinxをはじめよう 第3版

Sphinxをはじめよう 第3版

Amazon

  1. この冬、白い砂のアクアトープが全部見られる！さかなー🐟さかなー🐟さかなー🐟 17:13のあたりです😭↩
  2. https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html の冒頭「They are written as ...」より↩
  3. ただし、バックスラッシュが絡むと動きが違うそうです（そのため「基本的に同じもの」と紹介しました）。2連バッククォートで囲むとバックスラッシュはそのまま出力されますが、literalロールではバックスラッシュがエスケープとして機能するそうです↩
  4. https://github.com/ftnext/sphinx-new-tab-link/blob/v0.1.1/docs/guide.rst#L30↩
  5. このスライドは、PyCon APAC 2022でPEGについて話したスライドです。全体は以下からどうぞ ↩
  6. https://github.com/ftnext/2022_slides/blob/d081237c6c3d2cd514fca92a547ba65bc033c4f3/source/pyconapac_peg/en/introduction.rst.txt#L137↩