Module author: Georg Brandl
New in version 1.0.
この拡張を利用すると、同一のウェブサイト内にある多くの外部参照リンクを利用する際に、共通部分をパターン化することができます。例えば、バグトラッカーや、バージョン管理システムのウェブインタフェース、他のウェブサイトの中のサブページなどです。この拡張機能は、ベースとなるURLのエイリアスを提供します。サブのページの名前をつけるだけで、リンクを作成できるようになります。
Sphinxのissueトラッカー上の項目に対して、多くのリンクを作成したいとしましょう。各ページのURLは、 http://bitbucket.org/birkenfeld/sphinx/issue/num というURLになります。このURLを何度も何度もタイプするのは疲れますが、 extlinks を使うと、この繰り返し作業から解法されます。
この拡張は新しい設定値を追加します。:
この設定値は、外部サイト情報を持つ辞書になります。ユニークな短いエイリアス名をキーに持ち、 ベースのURLと prefix を値に持ちます。例えば、上記で挙げたissueトラッカーを表現する場合には、次のように設定します:
extlinks = {'issue': ('http://bitbucket.org/birkenfeld/sphinx/issue/%s',
'issue ')}
このような設定をすると、 :issue:`123` というように、エイリアス名をロールとして使用できます。このロールには http://bitbucket.org/birkenfeld/sphinx/issue/123 へのリンクが挿入されます。見て分かるように、ロールで与えられたターゲットは、ベースURLの %s に置き換えられます。
リンクの キャプション は、タプルの2つ目の要素の prefix によって表記が異なります。
他の相互リンクのためのロールのように、 :issue:`この問題 <123>` という、明示的な名前を指定する書き方も使うことができます。この場合、 prefix は利用されません。
Note
読み込み段階でロールからリンクが生成されるため、 linkcheck ビルダーなどでは通常のリンクとして扱われます。