sphinx.ext.extlinks -- 外部リンクを短縮表記させるマークアップ

モジュールの作者: Georg Brandl

バージョン 1.0 で追加.

この拡張を利用すると、同一のウェブサイト内にある多くの外部参照リンクを利用する際に、共通部分をパターン化できます。例えば、バグトラッカーや、バージョン管理システムのウェブインタフェース、他のウェブサイトの中のサブページなどです。この拡張機能は、ベースとなるURLのエイリアスを提供します。サブのページの名前をつけるだけで、リンクを作成できるようになります。

Sphinxのissueトラッカー上の項目に対して、多くのリンクを作成したいとしましょう。各ページのURLは、 https://github.com/sphinx-doc/sphinx/issues/num です。このURLを何度も何度もタイプするのは疲れますが、 extlinks を使うと、この繰り返し作業から解法されます。

この拡張は新しい設定値を追加します:

extlinks

This config value must be a dictionary of external sites, mapping unique short alias names to a base URL and a caption. For example, to create an alias for the above mentioned issues, you would add

extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
                      'issue %s')}

Now, you can use the alias name as a new role, e.g. :issue:`123`. This then inserts a link to https://github.com/sphinx-doc/sphinx/issues/123. As you can see, the target given in the role is substituted in the base URL in the place of %s.

The link caption depends on the second item in the tuple, the caption:

• If caption is None, the link caption is the full URL.

• If caption is a string, then it must contain %s exactly once. In this case the link caption is caption with the partial URL substituted for %s -- in the above example, the link caption would be issue 123.

To produce a literal % in either base URL or caption, use %%:

extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
                      '[K&R; page %s]')}

You can also use the usual "explicit title" syntax supported by other roles that generate links, i.e. :issue:`this issue <123>`. In this case, the caption is not relevant.

バージョン 4.0 で変更: Support to substitute by '%s' in the caption.

注釈

読み込み段階でロールからリンクが生成されるため、 linkcheck ビルダーなどでは通常のリンクとして扱われます。

extlinks_detect_hardcoded_links

If enabled, extlinks emits a warning if a hardcoded link is replaceable by an extlink, and suggests a replacement via warning. It defaults to False.

バージョン 4.5 で追加.