6章画像の変換と埋め込み

ここまででSphinxを使ったドキュメントの書き方はマスターです。 ここからは 一歩進んだドキュメントの書き方について見ていきましょう。

EPUBに変換してみよう では、画像の埋め込み方をかんたんに紹介しました。 本章では、画像を作るところから埋め込むところまでの一連の流れや使い方を紹介します。 Sphinxの画像に関するさまざまな機能を理解すると、高品質な画像を手軽に使えるようになります。

6.1　基本中の基本、 figure ディレクティブ

まずは基本形である figure ディレクティブをおさらいしましょう。

reST記法で画像を埋め込むには、 figure ディレクティブを用います。 画像を埋め込みたい位置に figure ディレクティブを記述し、画像ファイルとキャプション、説明文を指定します。

.. figure:: sphinx-logo.png

   Sphinxのロゴ

   ホルスの目と呼ばれる古代エジプトのシンボルをモチーフとしています

上記の例では.rstファイルと同じディレクトリの sphinx-logo.png を、「Sphinxのロゴ」というキャプションをつけて表示します。

figure ディレクティブの引数には以下のいずれかが指定できます。

  • .rstファイルが保存されているディレクトリからの相対パス

  • Sphinxプロジェクトのルートからの絶対パス（例： /images/sphinx-logo.png）

  • URL

上記のサンプルをHTMLに変換すると、以下のような出力が得られます。

図6-1: figureディレクティブの出力例

figure ディレクティブのオプション

figure ディレクティブには、画像の大きさやリンクに関するオプションが提供されています。 ...