def pull_role(
name: str,
rawtext: str,
text: str,
lineno: int,
inliner: Inliner,
options: Dict[str, Any] = {},
content: List[str] = []
) -> Tuple[List[IssueNode], List[system_message]]:
"""
Adds a link to the given pulll request on GitHub.
:param name: The local name of the interpreted role, the role name actually used in the document.
:param rawtext: A string containing the entire interpreted text input, including the role and markup.
:param text: The interpreted text content.
:param lineno: The line number where the interpreted text begins.
:param inliner: The :class:`docutils.parsers.rst.states.Inliner` object that called :func:`~.pull_role`.
It contains the several attributes useful for error reporting and document tree access.
:param options: A dictionary of directive options for customization (from the ``role`` directive),
to be interpreted by the function.
Used for additional attributes for the generated elements and other functionality.
:param content: A list of strings, the directive content for customization (from the ``role`` directive).
To be interpreted by the function.
:return: A list containing the created node, and a list containing any messages generated during the function.
.. clearpage::
"""
has_t, issue_number, repository = split_explicit_title(text)
issue_number = nodes.unescape(issue_number)
messages: List[system_message] = []
refnode: IssueNode
if has_t:
repository_parts = nodes.unescape(repository).split('/')
if len(repository_parts) != 2:
warning_message = inliner.document.reporter.warning(
f"Invalid repository '{repository}' for pull request #{issue_number}."
)
messages.append(warning_message)
else:
refnode = IssueNodeWithName(
repo_name=repository,
issue_number=issue_number,
refuri=make_github_url(*repository_parts) / "pull" /
str(int(issue_number)),
)
return [refnode], messages
pull_url = inliner.document.settings.env.app.config.github_pull_url
refnode = IssueNode(issue_number=issue_number,
refuri=pull_url / str(int(issue_number)))
return [refnode], messages
def repository_role(
name: str,
rawtext: str,
text: str,
lineno: int,
inliner: Inliner,
options: Dict[str, Any] = {},
content: List[str] = []
) -> Tuple[List[nodes.reference], List[system_message]]:
"""
Adds a link to the given repository on GitHub.
:param name: The local name of the interpreted role, the role name actually used in the document.
:param rawtext: A string containing the entire interpreted text input, including the role and markup.
:param text: The interpreted text content.
:param lineno: The line number where the interpreted text begins.
:param inliner: The :class:`docutils.parsers.rst.states.Inliner` object that called :func:`~.repository_role`.
It contains the several attributes useful for error reporting and document tree access.
:param options: A dictionary of directive options for customization (from the ``role`` directive),
to be interpreted by the function.
Used for additional attributes for the generated elements and other functionality.
:param content: A list of strings, the directive content for customization (from the ``role`` directive).
To be interpreted by the function.
:return: A list containing the created node, and a list containing any messages generated during the function.
"""
has_t, text, repo_name = split_explicit_title(text)
repo_name = nodes.unescape(repo_name)
repository_parts = nodes.unescape(repo_name).split('/')
if len(repository_parts) != 2:
return [], [
inliner.document.reporter.warning(
f"Invalid repository '{repo_name}'.")
]
# refnode: nodes.reference
if has_t:
refnode = nodes.reference(
text,
text,
refuri=str(make_github_url(*repository_parts)),
)
else:
refnode = GitHubObjectLinkNode(
name=repo_name,
refuri=make_github_url(*repository_parts),
)
return [refnode], []
def asset_role(
name: str,
rawtext: str,
text: str,
lineno: int,
inliner: Inliner,
options: Dict = {},
content: List[str] = []
) -> Tuple[Sequence[AssetNode], List[system_message]]:
"""
Adds a link to an asset.
:param name: The local name of the interpreted role, the role name actually used in the document.
:param rawtext: A string containing the entire interpreted text input, including the role and markup.
:param text: The interpreted text content.
:param lineno: The line number where the interpreted text begins.
:param inliner: The :class:`docutils.parsers.rst.states.Inliner` object that called :func:`~.source_role`.
It contains the several attributes useful for error reporting and document tree access.
:param options: A dictionary of directive options for customization (from the ``role`` directive),
to be interpreted by the function.
Used for additional attributes for the generated elements and other functionality.
:param content: A list of strings, the directive content for customization (from the ``role`` directive).
To be interpreted by the function.
:return: A list containing the created node, and a list containing any messages generated during the function.
"""
has_t, title, target = split_explicit_title(text)
title = nodes.unescape(title)
target = nodes.unescape(target)
if not has_t:
if target.startswith('~'):
target = target[1:]
title = pathlib.PurePosixPath(text[1:]).name
app = inliner.document.settings.env.app
base = app.config.assets_dir
node = AssetNode(rawtext,
title,
refuri=target,
source_file=PathPlus(base) / target,
**options)
return [node], []
def user_role(
name: str,
rawtext: str,
text: str,
lineno: int,
inliner: Inliner,
options: Dict[str, Any] = {},
content: List[str] = []
) -> Tuple[List[nodes.reference], List[system_message]]:
"""
Adds a link to the given user / organization on GitHub.
:param name: The local name of the interpreted role, the role name actually used in the document.
:param rawtext: A string containing the entire interpreted text input, including the role and markup.
:param text: The interpreted text content.
:param lineno: The line number where the interpreted text begins.
:param inliner: The :class:`docutils.parsers.rst.states.Inliner` object that called :func:`~.user_role`.
It contains the several attributes useful for error reporting and document tree access.
:param options: A dictionary of directive options for customization (from the ``role`` directive),
to be interpreted by the function.
Used for additional attributes for the generated elements and other functionality.
:param content: A list of strings, the directive content for customization (from the ``role`` directive).
To be interpreted by the function.
:return: A list containing the created node, and a list containing any messages generated during the function.
.. clearpage::
"""
has_t, text, username = split_explicit_title(text)
username = nodes.unescape(username)
messages: List[system_message] = []
if has_t:
refnode = nodes.reference(
text,
text,
refuri=str(GITHUB_COM / username),
)
else:
refnode = GitHubObjectLinkNode(
name=f"@{username}",
refuri=GITHUB_COM / username,
)
return [refnode], messages
def make_wikipedia_link(
name: str,
rawtext: str,
text: str,
lineno: int,
inliner: Inliner,
options: Dict = {},
content: List[str] = []
) -> Tuple[List[nodes.reference], List[system_message]]:
"""
Adds a link to the given article on :wikipedia:`Wikipedia`.
:param name: The local name of the interpreted role, the role name actually used in the document.
:param rawtext: A string containing the entire interpreted text input, including the role and markup.
:param text: The interpreted text content.
:param lineno: The line number where the interpreted text begins.
:param inliner: The :class:`docutils.parsers.rst.states.Inliner` object that called :func:`~.source_role`.
It contains the several attributes useful for error reporting and document tree access.
:param options: A dictionary of directive options for customization (from the ``role`` directive),
to be interpreted by the function.
Used for additional attributes for the generated elements and other functionality.
:param content: A list of strings, the directive content for customization (from the ``role`` directive).
To be interpreted by the function.
:return: A list containing the created node, and a list containing any messages generated during the function.
"""
env = inliner.document.settings.env
lang = env.config.wikipedia_lang
text = nodes.unescape(text)
has_explicit, title, target = split_explicit_title(text)
m = re.match(r":(.*?):(.*)", target)
if m:
lang, target = m.groups()
if not has_explicit:
title = target
lang_url = URL(base_url % lang)
ref = lang_url / quote(target.replace(' ', '_'), safe='')
node = nodes.reference(rawtext, title, refuri=str(ref), **options)
return [node], []
def parse_explicit_title(text: str) -> Tuple[str, Optional[str]]:
match = PAT_EXPLICIT_TITLE.match(text)
if match:
return unescape(match["target"]), unescape(match["label"])
return (unescape(text), None)
def source_role(
name: str,
rawtext: str,
text: str,
lineno: int,
inliner: Inliner,
options: Dict = {},
content: List[str] = []
) -> Tuple[Sequence[nodes.Node], List[system_message]]:
"""
Adds a link to the given Python source file in the documentation or on GitHub.
:param name: The local name of the interpreted role, the role name actually used in the document.
:param rawtext: A string containing the entire interpreted text input, including the role and markup.
:param text: The interpreted text content.
:param lineno: The line number where the interpreted text begins.
:param inliner: The :class:`docutils.parsers.rst.states.Inliner` object that called :func:`~.source_role`.
It contains the several attributes useful for error reporting and document tree access.
:param options: A dictionary of directive options for customization (from the ``role`` directive),
to be interpreted by the function.
Used for additional attributes for the generated elements and other functionality.
:param content: A list of strings, the directive content for customization (from the ``role`` directive).
To be interpreted by the function.
:return: A list containing the created node, and a list containing any messages generated during the function.
.. versionchanged:: 2.8.0
Now returns a sequence of :class:`nodes.reference <docutils.nodes.reference>` and
:class:`addnodes.pending_xref <sphinx.addnodes.pending_xref>` as the first tuple element,
rather than :class:`nodes.reference <docutils.nodes.reference>` and
:class:`addnodes.pending_xref <sphinx.addnodes.only>` as in previous versions.
"""
has_t, title, target = split_explicit_title(text)
title = nodes.unescape(title)
target = nodes.unescape(target)
env = inliner.document.settings.env
config = env.app.config
nodes_: List[nodes.Node] = []
messages: List[system_message] = []
refnode: nodes.Node
if config.source_link_target == "sphinx":
if target.endswith("/__init__.py"):
pagename = "_modules/" + target.rsplit('/', 1)[0]
else:
pagename = "_modules/" + target.replace(".py", '')
# refnode = addnodes.only(expr="html")
# refnode += addnodes.pending_xref(
refnode = _make_viewcode_node(
title,
pagename,
env,
)
# refnode = addnodes.pending_xref(
# title,
# nodes.inline(title, title),
# reftype="viewcode",
# refdomain="std",
# refexplicit=False,
# reftarget=pagename,
# refid=title,
# refdoc=env.docname,
# )
nodes_.append(refnode)
elif config.source_link_target == "github":
refnode = nodes.reference(
title,
title,
refuri=str(config.github_source_url / target),
)
nodes_.append(refnode)
else:
message = inliner.document.reporter.error(f"Unsupported source link target '{config.source_link_target}'.")
messages.append(message)
return nodes_, messages
def _get_rawsource(node):
# Docutils < 0.18 has rawsource attribute, otherwise, build it.
if hasattr(node, 'rawsource'):
return node.rawsource
return nodes.unescape(node, restore_backslashes=True)