Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Allow custom target in manpage role #11825

Merged
merged 6 commits into from
Jan 17, 2024
Merged

Allow custom target in manpage role #11825

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
40cb3c7
Allow custom target in manpage role
n-peugnet Dec 29, 2023
d6bf462
Merge branch 'master' into manpage-custom-text
AA-Turner Jan 16, 2024
ffc2591
Use innernodeclass
AA-Turner Jan 16, 2024
2623f70
Use a custom ReferenceRole subclass
AA-Turner Jan 16, 2024
b6910ba
Update doc/usage/restructuredtext/roles.rst
AA-Turner Jan 16, 2024
b5e3ac1
Add a missing space
AA-Turner Jan 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 3 additions & 0 deletions doc/usage/restructuredtext/roles.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,9 @@ different style:
``:manpage:`ls(1)``` displays :manpage:`ls(1)`. Creates a hyperlink to an
external site rendering the manpage if :confval:`manpages_url` is defined.

.. versionchanged:: 7.3
Allowed to specify a custom target inside ``<>`` like hyperlinks.
AA-Turner marked this conversation as resolved.
Show resolved Hide resolved

.. rst:role:: menuselection

Menu selections should be marked using the ``menuselection`` role. This is
Expand Down
2 changes: 1 addition & 1 deletion sphinx/addnodes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -549,7 +549,7 @@ class literal_strong(nodes.strong, not_smartquotable):
"""


class manpage(nodes.Inline, nodes.FixedTextElement):
class manpage(nodes.reference, nodes.FixedTextElement):
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure if this change is really needed.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think changing the base class of manpage is not the way to go. Concerning the formatting, I think we shouldn't change it for now.

@picnixz: I tried reverting this change but I get the same formatting results in HTML. It must come from something else.
We can also wait for another opinion on the formatting changes, and if it is OK I can modify the expected results in the tests, and add a changelog entry etc.

Otherwise I don't really know where to look for this formatting change in the code. I will continue to try some things but I don't know if I will manage to keep the existing HTML formatting.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be ok for you to postpone it for a few weeks/months? because I won't have time for in-depth review before march/april.

If anyone else has time to dig or wants to discuss feel free to ignore my opinion as I don't mind both formats actually (just that I want to keep changes minimal if possible, especially if it concerns base classes)

"""Node for references to manpages."""


Expand Down
3 changes: 2 additions & 1 deletion sphinx/roles.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@
'kbd': nodes.literal,
'mailheader': addnodes.literal_emphasis,
'makevar': addnodes.literal_strong,
'manpage': addnodes.manpage,
'mimetype': addnodes.literal_emphasis,
'newsgroup': addnodes.literal_emphasis,
'program': addnodes.literal_strong, # XXX should be an x-ref
Expand Down Expand Up @@ -398,6 +397,8 @@ def code_role(name: str, rawtext: str, text: str, lineno: int,
specific_docroles: dict[str, RoleFunction] = {
# links to download references
'download': XRefRole(nodeclass=addnodes.download_reference),
# links to manpages
'manpage': XRefRole(nodeclass=addnodes.manpage),
# links to anything
'any': AnyXRefRole(warn_dangling=True),

Expand Down
3 changes: 1 addition & 2 deletions sphinx/transforms/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -389,8 +389,7 @@ class ManpageLink(SphinxTransform):

def apply(self, **kwargs: Any) -> None:
for node in self.document.findall(addnodes.manpage):
manpage = ' '.join([str(x) for x in node.children
if isinstance(x, nodes.Text)])
manpage = node['reftarget']
pattern = r'^(?P<path>(?P<page>.+)[\(\.](?P<section>[1-9]\w*)?\)?)$'
info = {'path': manpage,
'page': manpage,
Expand Down