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 validate_config(app: Sphinx, config: ToolboxConfig):
r"""
Validate the provided configuration values.
See :class:`~sphinx_toolbox.config.ToolboxConfig` for a list of the configuration values.
:param app: The Sphinx app.
:param config:
:type config: :class:`~sphinx.config.Config`
"""
config.source_link_target = str(config.source_link_target).lower().strip()
if config.source_link_target not in {"sphinx", "github"}:
raise InvalidOptionError("Invalid value for 'source_link_target'.")
if not config.github_username:
raise MissingOptionError("The 'github_username' option is required.")
else:
config.github_username = str(config.github_username)
if not config.github_repository:
raise MissingOptionError("The 'github_repository' option is required.")
else:
config.github_repository = str(config.github_repository)
config.github_url = make_github_url(config.github_username,
config.github_repository)
config.github_source_url = config.github_url / "blob" / "master"
config.github_issues_url = config.github_url / "issues"
config.github_pull_url = config.github_url / "pull"
add_nbsp_substitution(config)
def test_depart_issue_node():
node = IssueNode(7680, make_github_url("pytest-dev", "pytest") / "issues/7680")
translator = FakeTranslator()
assert not node.has_tooltip
depart_issue_node(translator, node) # type: ignore
assert translator.body == []
node = IssueNode(7680, make_github_url("pytest-dev", "pytest") / "issues/7680")
translator = FakeTranslator()
node.has_tooltip = True
depart_issue_node(translator, node) # type: ignore
assert translator.body == ["</abbr>"]
def validate_config(app: Sphinx, config: ToolboxConfig):
r"""
Validate the provided configuration values.
See :class:`~sphinx_toolbox.config.ToolboxConfig` for a list of the configuration values.
:param app: The Sphinx app.
:param config:
:type config: :class:`~sphinx.config.Config`
"""
if not config.github_username:
raise MissingOptionError("The 'github_username' option is required.")
else:
config.github_username = str(config.github_username)
if not config.github_repository:
raise MissingOptionError("The 'github_repository' option is required.")
else:
config.github_repository = str(config.github_repository)
config.github_url = make_github_url(config.github_username, config.github_repository)
config.github_source_url = config.github_url / "blob" / "master"
config.github_issues_url = config.github_url / "issues"
config.github_pull_url = config.github_url / "pull"
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 run(self) -> List[nodes.Node]:
"""
Process the content of the shield directive.
"""
username, repository = self.get_repo_details()
workflow = quote(self.options["workflow"])
self.arguments = [
str(
make_github_url(username, repository) / "workflows" /
workflow / "badge.svg")
]
self.options["target"] = str(
make_github_url(username, repository) /
f"actions?query=workflow%3A%22{workflow}%22")
return super().run()
def test_visit_issue_node():
node = IssueNode(7680, make_github_url("pytest-dev", "pytest") / "issues/7680")
translator = FakeTranslator()
assert not node.has_tooltip
visit_issue_node(translator, node) # type: ignore
assert translator.body == ['<abbr title="Add --log-cli option">']
assert node.has_tooltip
def test_depart_issue_node():
node = IssueNode(7680,
make_github_url("pytest-dev", "pytest") / "issues/7680")
translator = FakeTranslator()
assert not node.has_tooltip
with pytest.warns(DeprecationWarning):
issues.depart_issue_node(translator, node)
assert translator.body == []
node = IssueNode(7680,
make_github_url("pytest-dev", "pytest") / "issues/7680")
translator = FakeTranslator()
node.has_tooltip = True
with pytest.warns(DeprecationWarning):
issues.depart_issue_node(translator, node)
assert translator.body == ["</abbr>"]
def run(self) -> Sequence[nodes.Node]: # type: ignore
"""
Process the content of the directive.
"""
if "hooks" in self.options:
hooks = self.options["hooks"]
else:
cwd = PathPlus.cwd()
for directory in (cwd, *cwd.parents):
hook_file = directory / ".pre-commit-hooks.yaml"
if hook_file.is_file():
hooks_dict = YAML(typ="safe", pure=True).load(hook_file.read_text())
hooks = [h["id"] for h in hooks_dict]
break
else:
warnings.warn("No hooks specified and no .pre-commit-hooks.yaml file found.")
return []
repo = make_github_url(self.env.config.github_username, self.env.config.github_repository)
config: _Config = {"repo": str(repo)}
if "rev" in self.options:
config["rev"] = self.options["rev"]
config["hooks"] = [{"id": hook_name} for hook_name in hooks]
if "args" in self.options:
config["hooks"][0]["args"] = self.options["args"]
targetid = f'pre-commit-{self.env.new_serialno("pre-commit"):d}'
targetnode = nodes.section(ids=[targetid])
yaml_dumper = YAML()
yaml_dumper.default_flow_style = False
yaml_output_stream = StringIO()
yaml_dumper.dump([config], stream=yaml_output_stream)
yaml_output = yaml_output_stream.getvalue()
if not yaml_output:
return []
content = f".. code-block:: yaml\n\n{indent(yaml_output, ' ')}\n\n"
view = StringList(content.split('\n'))
pre_commit_node = nodes.paragraph(rawsource=content)
self.state.nested_parse(view, self.content_offset, pre_commit_node)
pre_commit_node_purger.add_node(self.env, pre_commit_node, targetnode, self.lineno)
return [pre_commit_node]
def test_visit_issue_node():
node = IssueNode(7680,
make_github_url("pytest-dev", "pytest") / "issues/7680")
translator = FakeTranslator()
assert not node.has_tooltip
with pytest.warns(DeprecationWarning):
issues.visit_issue_node(translator, node)
assert translator.body == ['<abbr title="Add --log-cli option">']
assert node.has_tooltip
def test_make_github_url():
url = make_github_url("domdfcoding", "sphinx-toolbox")
assert isinstance(url, RequestsURL)
assert url == RequestsURL("https://github.com/domdfcoding/sphinx-toolbox")