`sphinx.ext.extlinks` – Balisage pour raccourcir les liens externes¶

Auteur du module : Georg Brandl

Ajouté dans la version 1.0.

Cette extension est destinée à aider avec un modèle commun d’avoir beaucoup de liens externes qui pointent vers des URLs sur un seul et même site, par exemple des liens vers des trackers de bugs, des interfaces web de contrôle de version, ou simplement des sous-pages dans d’autres sites. Pour ce faire, il fournit des alias aux URL de base, de sorte que vous n’avez qu’à donner le nom de la sous-page lors de la création d’un lien.

Supposons que vous souhaitiez inclure de nombreux liens vers des problèmes sur le tracker Sphinx, sur https://github.com/sphinx-doc/sphinx/issues/num. Taper cette URL encore et encore est fastidieux, donc vous pouvez utiliser extlinks pour éviter de vous répéter.

The extension adds a config value:

extlinks¶

Type:: dict[str, tuple[str, str | None]]
Défaut:: {}

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.

Modifié dans la version 4.0: Support to substitute by “%s” in the caption.

Note

Puisque les liens sont générés à partir du rôle à l’étape de la lecture, ils apparaissent comme des liens ordinaires vers, par exemple, le constructeur linkcheck.

extlinks_detect_hardcoded_links¶

Type:: bool
Défaut:: False

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

Ajouté dans la version 4.5.

sphinx.ext.extlinks – Balisage pour raccourcir les liens externes¶

`sphinx.ext.extlinks` – Balisage pour raccourcir les liens externes¶