-
Notifications
You must be signed in to change notification settings - Fork 25
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.
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
Make argument and option section IDs more unique #44
Conversation
Looks like RTD is failing because CommonMark is an optional dependency but needed to generate the docs. |
@@ -93,7 +93,8 @@ def print_action_groups(data, nested_content, markdown_help=False, settings=None | |||
if 'action_groups' in data: | |||
for action_group in data['action_groups']: | |||
# Every action group is comprised of a section, holding a title, the description, and the option group (members) | |||
section = nodes.section(ids=[action_group['title'].replace(' ', '-').lower()]) | |||
title_as_id = action_group['title'].replace(' ', '-').lower() | |||
section = nodes.section(ids=[f"{id_prefix}-{title_as_id}"]) | |||
section += nodes.title(action_group['title'], action_group['title']) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am observing a similar problem with labels: specifically with autosectionlabel
and similar modules, e.g. nbsphinx
.
This is specifically a problem because these modules generate these handles from rawsource or text, so to fix this a prefix also has to be added to rawsource
and text
in the title objects.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are you talking about the nodes.title
object right here? Are rawsource
and text
the names of the arguments being passed to it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't really understand how we can add a prefix to text
without changing the actual text of the title.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes and I can go a step further https://github.com/sphinx-doc/sphinx/blob/3b907a1caab14fac7b1a66a0f3f30d969b0707b2/sphinx/ext/autosectionlabel.py#L41-L55 is where these links are created and at the end of that the warning gets generated.
But you are completely correct: changing the section label without changing the text is not possible right now.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A solution for right now might be to add a configuration option to add the subcommand to the headlines...
Sorry, I may have hijacked your PR without a good reason. It is probably only a tangential issue and not the same...
Also, this was not supposed to be a "review" but I wanted to give a link to the source...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I appreciate you bringing it up either way. I think autosectionlabel may just not be compatible with this package. Does this PR and this option https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html#confval-autosectionlabel_prefix_document fix this at all?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It does not fix this issue.
The issue is raised by having the same section title in the same document multiple times, e.g. Named Options. Adding the document to the label does not solve the issue.
It can only be solved by deactivating autosectionlabel
or by suppressing the autosectionlabel
Warning.
c995905
to
849ef05
Compare
Closes #43
This adds the module name and function name (attribute name from the module) to the beginning of the section ID for Named Arguments and options sections. This allows the IDs to be unique and for sphinx to keep section numbering consistent. See the referenced issue for more information.
I'm not really sure how to add a test for this. Also this does not effect subcommand section IDs as I'm not sure I understand how those are structured. This PR solves my immediate problem.