sphinx.ext.extlinks – 外部リンクの短縮化のためのマークアップ¶
モジュール作者: Georg Brandl
バージョン 1.0 で追加。
この拡張機能は、バグトラッカー、バージョン管理Webインターフェース、または単に他のWebサイトのサブページなど、同じサイトを指す多くの外部リンクという一般的なパターンを処理するのに役立つことを目的としています。これは、ベースURLへのエイリアスを提供することで実現されており、リンクを作成する際にサブページ名のみを指定するだけで済みます。
Sphinx トラッカーの https://github.com/sphinx-doc/sphinx/issues/numにある多くの問題へのリンクを含めたいとしましょう。このURLを何度も入力するのは面倒なので、extlinks を使用して繰り返しを避けることができます。
この拡張機能は設定値を追加します
- extlinks¶
この設定値は、外部サイトの辞書でなければなりません。一意の短いエイリアス名を、ベースURLとキャプションにマッピングします。たとえば、上記の問題のエイリアスを作成するには、次のように追加します。
extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s', 'issue %s')}
これで、エイリアス名を新しいロールとして使用できます（例：
:issue:`123`）。これにより、https://github.com/sphinx-doc/sphinx/issues/123へのリンクが挿入されます。ご覧のとおり、ロールで指定されたターゲットは、%sの場所にベースURLに置換されます。リンクのキャプションは、タプルの2番目の項目であるキャプションによって決まります。
キャプションが
Noneの場合、リンクのキャプションは完全なURLになります。キャプションが文字列の場合、
%sを正確に1回含む必要があります。この場合、リンクのキャプションは、部分的なURLが%sに置換されたキャプションになります。上記の例では、リンクのキャプションはissue 123になります。
ベースURLまたはキャプションにリテラルの
%を作成するには、%%を使用します。extlinks = {'KnR': ('https://example.org/K%%26R/page/%s', '[K&R; page %s]')}
リンクを生成する他のロールでサポートされている通常の「明示的なタイトル」構文（例：
:issue:`this issue <123>`）も使用できます。この場合、キャプションは関係ありません。バージョン 4.0 で変更: キャプションに「%s」を置換するサポート。
注記
リンクは読み込み段階でロールから生成されるため、linkcheckビルダーなどに対する通常のリンクとして表示されます。
- extlinks_detect_hardcoded_links¶
有効にすると、extlinks はハードコーディングされたリンクを extlink で置き換え可能である場合に警告を出し、警告を介して置き換えを提案します。デフォルトは
Falseです。バージョン 4.5 で追加。