ITADN

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

#282Openjeertmans 创建于 2025-06-25
documentationneeds-triage
J
jeertmanscommented
### Terms - [x] Checked the [existing issues](https://github.com/jeertmans/DiffeRT/issues?q=is%3Aissue+label%3Adocumentation+) and [discussions](https://github.com/jeertmans/DiffeRT/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, https://github.com/jeertmans/DiffeRT/blob/3e67ec4c98ba3893d04f6c704c74352e5f2b5e1e/docs/source/conf.py#L129-L143 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](https://www.sphinx-doc.org/en/master/development/tutorials/extending_syntax.html), as done [for the Bokeh documentation](https://github.com/bokeh/bokeh/blob/81be65bfddc43ba57730a2014db9f71a4a75a736/src/bokeh/sphinxext/_internal/bokeh_roles.py#L81-L238) (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.
0 条评论