Add autosectionlabel_full_reference configuration variable #13076
Conversation
There was a problem hiding this comment.
Thanks, that's a nice addition but I'd like you to address the following points (especially for improving test coverage because I think the current algorithm will not work if there are non-section nodes between two sections).
In addition, we'll need a CHANGELOG entry for this one since it's a new feature.
| * :ref:`index:Installation:For UNIX users:Linux:Command` | ||
| * :ref:`index:Installation:For UNIX users:FreeBSD` | ||
| * :ref:`index:Installation:For UNIX users:FreeBSD:Command` | ||
| * :ref:`index:Installation:This one's got an apostrophe` |
There was a problem hiding this comment.
Can you check check with numbers in titles as well as with :math: blocks please? and with literal (double backquotes). Can we also use :ref: in a title? (if not, no need for the coverage).
Additionally, can you test when you specify a custom label before an inner title? as well as content in-between two titles (in other words, try to see if it's possible to construct a doctree with the following tree: "section -> non-section -> section") so that the parent of the second section is a non-section node.
There was a problem hiding this comment.
Would adding an image in between suffice? e.g.
Section
-------
Here is an image or I could use a figure?
.. image:: test.png
Sub Section
~~~~~~~~~~~
See previous image...
There was a problem hiding this comment.
Unfortunately, the image and subsection would be sibling nodes and not parent->child nodes. Maybe it's not possible to actually have a parent node that is not a section's node but I need to check that (it's midnight here so I won't do it today).
There was a problem hiding this comment.
I have tested with numbers in sections
There was a problem hiding this comment.
I have tried to added all the other comments, and added texinfo and latex tests and the test includes another rst file, to check how references worked there.
How is it looking now?
In usage, updated as suggested in review Added versionadded 8.2 for the new feature Walked node tree looking only for nodes.section type. Prefixed internally used functions with _. Added bool type to add_config_value calls Used Python f'' string for efficiency Overrides document.settings.id_prefix so that suitable references are created in case of any duplicate section hierarchy. Tests for these are created too. The autosectionlabel_full_reference tests now include another file to check multiple file references. When using autosectionlabel_full_reference in texinfo, the filename is not prefixed in references. Added texinfo tests. When using autosectionlabel_full_reference in latex, the filename is not prefixed in references. Added latex tests All new tests pass All type-checks pass
sphinx/ext/autosectionlabel.py
Outdated
| @@ -20,7 +20,7 @@ | |||
| logger = logging.getLogger(__name__) | |||
|
|
|||
|
|
|||
| def get_node_depth(node: Node) -> int: | |||
| def _get_node_depth(node: Node) -> int: | |||
There was a problem hiding this comment.
Ah maybe I wasn't clear. Old APIs are fine to be kept untouched (because we don't want to break packages) but it's good if new APIs can be designed with a good scope.
…ation Undo _get_node_depth rename Change _find_node_parents to _get_all_node_parent_section_titles to describe more fully what the function does and _ prefix is just for internal use.
…d texinfo writers
This reverts commit 9072d62.
This makes the full section id available to be used for cross references. Note: The original short id is still needed by other functionality. I.e. the full id cannot replace the short one, `node['ids'][0] = labelid` because then TOC and sectnum:: functionality is broken in the HTML output.
Subject: Enable the autosectionlabel extension to create more unique references
Feature or Bugfix
Purpose
This pull-request includes an option that makes the usable references that include the section name hierarchy in the reference string.
Detail
Relates