12年間 Sphinx を使っていても「Sphinxをはじめよう第3版」で学びがあった

Sphinxをはじめよう第3版 を読んだのでまとめておく。
ライフログをあさってみるとSphinxは12年位前に触り始めているみたい。
細々と使い続けていたけれど、4年前からは会社で手順書などをローカルのWebサイトに公開して活用している。
4年の成果は、rstファイルが200弱、画像ファイルが700強、固定ファイルが200強。
結構頑張って書いてると思う。

それだけ使っていても本著を読んだ学びがあった。

名前なしハイパーリンク

_ が一つの「名前付きハイパーリンク参照」で同じ名前に異なるリンク先を指定して WARNING が出ていたけれど __ にすることで怒られなくなった。

`GitHub hokorobi <https://github.com/hokorobi>`__

画像は figure ディレクティブ

基本的には image ディレクティブを使って、見出しだったりサイズ指定を使いたいときだけ figure ディレクティブを使っていた。
本著では figure ディレクティブの説明しかなかったので、自分が使うのもすべて figure ディレクティブに置換した。

定義リスト

用語
  用語の説明

みたいなの。引用と区別されているのを知らなかった。

参照

ずっとセクションに紐づけて使っていたので、こういう使い方ができるのは知らなかった。

:ref:`リンクタイトル <ラベル名>`

ルビ

sphinxcontrib-textstyle で使えるみたい。使う機会がなかったので忘れていた？

別ファイルへのリンク

ずっとセクション前にラベルを書いて :ref: を使っていた。

:doc:`拡張子なしファイル名`

parsed-literal

reST を解釈してくれるリテラル。あんまり使わなそう。

.. parsed-literal::

置換

画像 |gazou| をインラインで埋め込んでくれる。

.. |gazou| image:: gazou.png

Sphinxをはじめよう第3版 はいいぞ。