[DOC] Add custom roles for GitHub links (issues, PRs, and users)

[jeertmans]

Terms

• Checked the existing issues and discussions to see if my issue had not already been reported;

Describe the issue

Currently, we use MyST-Parser's myst_url_schemes configuration variable, here,

DiffeRT/docs/source/conf.py

Lines 129 to 143 in 3e67ec4

	"gh-pr": {
	"url": "https://github.com/executablebooks/MyST-Parser/pull/{{path}}#{{fragment}}",
	"title": "PR #{{path}}",
	"classes": ["github"],
	},
	"gh-issue": {
	"url": "https://github.com/executablebooks/MyST-Parser/issue/{{path}}#{{fragment}}",
	"title": "Issue #{{path}}",
	"classes": ["github"],
	},
	"gh-user": {
	"url": "https://github.com/{{path}}",
	"title": "@{{path}}",
	"classes": ["github"],
	},

to customize the appearance of links to GitHub issues, PRs, or users. However, it only applies to Markdown files, and not RST files (including Python docstrings).

It would be nice to also have custom roles for GitHub links present in RST files.

Affected page(s)

All pages (generated from RST files or Python documentation) referencing GitHub links.

Issue type

Documentation enhancement

Recommended fix or suggestions

A possibility would be to define custom Sphinx roles, as done for the Bokeh documentation (however, this example does not include the GitHub logo).

This should be relatively easy. A better solution might be to rely on MyST-Parser to parse those links (as it already does for Markdown), but I don't know if this is feasible.