63 lines
2.0 KiB
Python
63 lines
2.0 KiB
Python
"""Custom reStructuredText entities/helpers for referencing entries in the
|
|
librsvg source tree.
|
|
|
|
For any changes made in this module, please ensure
|
|
``devel-docs/devel_docs_mod_guide.rst`` is updated accordingly, if necessary.
|
|
|
|
For help/reference on modifying these, see:
|
|
|
|
- https://www.sphinx-doc.org/en/master/development/tutorials/extending_syntax.html
|
|
- https://docutils.sourceforge.io/docs/howto/rst-roles.html
|
|
- https://protips.readthedocs.io/link-roles.html
|
|
- https://www.sphinx-doc.org/en/master/extdev/utils.html#sphinx.util.docutils.SphinxRole
|
|
- https://www.sphinx-doc.org/en/master/extdev/utils.html#sphinx.util.docutils.ReferenceRole
|
|
- https://github.com/sphinx-doc/sphinx/blob/master/sphinx/roles.py
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from docutils.nodes import reference
|
|
from sphinx.util.docutils import ReferenceRole
|
|
|
|
BASE_URL = "https://gitlab.gnome.org/GNOME/librsvg/-/tree"
|
|
|
|
|
|
class SourceRole(ReferenceRole):
|
|
"""A custom Sphinx role for referencing entries in the librsvg source tree.
|
|
"""
|
|
|
|
def run(self):
|
|
ref, _, path = self.target.rpartition(":")
|
|
|
|
if path.startswith("/"):
|
|
msg = self.inliner.reporter.error(
|
|
f"Invalid source tree entry path: {path!r}", line=self.lineno
|
|
)
|
|
prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
|
|
|
|
return [prb], [msg]
|
|
|
|
if ref:
|
|
# 12 <= 9 characters + elipsis (3 periods);
|
|
# 12, to allow `librsvg-X.YZ`.
|
|
short_ref = f"{ref[:9]}..." if len(ref) > 12 else ref
|
|
else:
|
|
short_ref = ref = "main"
|
|
|
|
node = reference(
|
|
self.rawtext,
|
|
(
|
|
self.title if self.has_explicit_title
|
|
else path or 'the source tree' if ref == "main"
|
|
else f"{path or 'the source tree'} (@ {short_ref})"
|
|
),
|
|
refuri=f"{BASE_URL}/{ref}/{path}",
|
|
**self.options,
|
|
)
|
|
|
|
return [node], []
|
|
|
|
|
|
def setup(app):
|
|
app.add_role("source", SourceRole())
|