librsvg source for verification 2026-05-22
This commit is contained in:
216
devel-docs/_extensions/internals.py
Normal file
216
devel-docs/_extensions/internals.py
Normal file
@@ -0,0 +1,216 @@
|
||||
"""Custom reStructuredText entities/helpers for referencing entities in the
|
||||
librsvg internals documentation.
|
||||
|
||||
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/development/tutorials/adding_domain.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 literal, reference
|
||||
from sphinx.domains import Domain
|
||||
from sphinx.util.docutils import ReferenceRole
|
||||
|
||||
BASE_URL = "https://gnome.pages.gitlab.gnome.org/librsvg/internals"
|
||||
|
||||
|
||||
class CrateRole(ReferenceRole):
|
||||
"""A custom Sphinx role for referencing crates in the librsvg internals
|
||||
documentation.
|
||||
"""
|
||||
|
||||
def run(self):
|
||||
node = reference(
|
||||
self.rawtext,
|
||||
refuri=f"{BASE_URL}/{self.target}/index.html",
|
||||
**self.options,
|
||||
)
|
||||
node += literal(self.rawtext, self.title)
|
||||
|
||||
return [node], []
|
||||
|
||||
|
||||
class ModuleRole(ReferenceRole):
|
||||
"""A custom Sphinx role for referencing modules in the librsvg internals
|
||||
documentation.
|
||||
"""
|
||||
|
||||
def run(self):
|
||||
components = self.target.split("::")
|
||||
|
||||
try:
|
||||
*parents, module = components
|
||||
if not parents:
|
||||
raise ValueError
|
||||
except ValueError:
|
||||
msg = self.inliner.reporter.error(
|
||||
f"Invalid module target: {self.target!r}", line=self.lineno
|
||||
)
|
||||
prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
|
||||
|
||||
return [prb], [msg]
|
||||
|
||||
node = reference(
|
||||
self.rawtext,
|
||||
refuri=f"{BASE_URL}/{'/'.join(parents)}/{module}/index.html",
|
||||
**self.options,
|
||||
)
|
||||
node += literal(
|
||||
self.rawtext, self.title if self.has_explicit_title else module
|
||||
)
|
||||
|
||||
return [node], []
|
||||
|
||||
|
||||
class TopLevelRole(ReferenceRole):
|
||||
"""A custom Sphinx role for referencing top-level entities in the librsvg
|
||||
internals documentation.
|
||||
"""
|
||||
|
||||
def __init__(self, target_kind: str, *, target_is_callable: bool = False):
|
||||
super().__init__()
|
||||
self.target_kind = target_kind
|
||||
self.target_is_callable = target_is_callable
|
||||
|
||||
def run(self):
|
||||
*parents, item = self.target.split("::")
|
||||
|
||||
if not parents:
|
||||
msg = self.inliner.reporter.error(
|
||||
f"Invalid {self.target_kind} target: {self.target!r}",
|
||||
line=self.lineno,
|
||||
)
|
||||
prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
|
||||
|
||||
return [prb], [msg]
|
||||
|
||||
node = reference(
|
||||
self.rawtext,
|
||||
refuri=(
|
||||
f"{BASE_URL}/{'/'.join(parents)}/{self.target_kind}"
|
||||
f".{item}.html"
|
||||
),
|
||||
**self.options,
|
||||
)
|
||||
node += literal(
|
||||
self.rawtext,
|
||||
(
|
||||
self.title if self.has_explicit_title
|
||||
else f"{item}()" if self.target_is_callable
|
||||
else item
|
||||
),
|
||||
)
|
||||
|
||||
return [node], []
|
||||
|
||||
|
||||
class MemberRole(ReferenceRole):
|
||||
"""A custom Sphinx role for referencing members of structs, enums, etc
|
||||
in the librsvg internals documentation.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
target_kind: str,
|
||||
parent_tag: str,
|
||||
member_tag: str,
|
||||
*,
|
||||
target_is_callable: bool = False,
|
||||
):
|
||||
super().__init__()
|
||||
self.target_kind = target_kind
|
||||
self.parent_tag = parent_tag
|
||||
self.member_tag = member_tag
|
||||
self.target_is_callable = target_is_callable
|
||||
|
||||
def run(self):
|
||||
show_parent = not self.target.startswith("~")
|
||||
target = self.target if show_parent else self.target[1:]
|
||||
components = target.split("::")
|
||||
|
||||
try:
|
||||
*parents, parent, member = components
|
||||
if not parents:
|
||||
raise ValueError
|
||||
except ValueError:
|
||||
msg = self.inliner.reporter.error(
|
||||
f"Invalid {self.target_kind} target: {target!r}",
|
||||
line=self.lineno,
|
||||
)
|
||||
prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
|
||||
|
||||
return [prb], [msg]
|
||||
|
||||
node = reference(
|
||||
self.rawtext,
|
||||
refuri=(
|
||||
f"{BASE_URL}/{'/'.join(parents)}/{self.parent_tag}"
|
||||
f".{parent}.html#{self.member_tag}.{member}"
|
||||
),
|
||||
**self.options,
|
||||
)
|
||||
|
||||
if not self.has_explicit_title:
|
||||
title = f"{parent}::{member}" if show_parent else member
|
||||
|
||||
node += literal(
|
||||
self.rawtext,
|
||||
(
|
||||
self.title if self.has_explicit_title
|
||||
else f"{title}()" if self.target_is_callable
|
||||
else title
|
||||
),
|
||||
)
|
||||
|
||||
return [node], []
|
||||
|
||||
|
||||
class InternalsDomain(Domain):
|
||||
"""A custom Sphinx domain for referencing the librsvg internals docs."""
|
||||
|
||||
name = "internals"
|
||||
label = "Librsvg Internals Docs"
|
||||
roles = {
|
||||
"crate": CrateRole(),
|
||||
"module": ModuleRole(),
|
||||
|
||||
# Top-level entities
|
||||
"struct": TopLevelRole("struct"),
|
||||
"enum": TopLevelRole("enum"),
|
||||
"trait": TopLevelRole("trait"),
|
||||
"type": TopLevelRole("type"),
|
||||
"fn": TopLevelRole("fn", target_is_callable=True),
|
||||
"macro": TopLevelRole("macro"),
|
||||
"constant": TopLevelRole("constant"),
|
||||
"static": TopLevelRole("static"),
|
||||
|
||||
# Member entities
|
||||
"struct-field": MemberRole("struct field", "struct", "structfield"),
|
||||
"struct-method": MemberRole(
|
||||
"struct method", "struct", "method", target_is_callable=True
|
||||
),
|
||||
"enum-variant": MemberRole("enum variant", "enum", "variant"),
|
||||
"trait-method": MemberRole(
|
||||
"provided trait method", "trait", "method", target_is_callable=True
|
||||
),
|
||||
"trait-tymethod": MemberRole(
|
||||
"required trait method",
|
||||
"trait",
|
||||
"tymethod",
|
||||
target_is_callable=True,
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.add_domain(InternalsDomain)
|
||||
62
devel-docs/_extensions/source.py
Normal file
62
devel-docs/_extensions/source.py
Normal file
@@ -0,0 +1,62 @@
|
||||
"""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())
|
||||
Reference in New Issue
Block a user