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.
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.
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.
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.
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.
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.
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.
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.
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.