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.

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

toctree, use document nesting instead of domain nesting when adding domain objects #12367

Merged
merged 6 commits into from
Jul 14, 2024

Conversation

jakobandersen
Copy link
Contributor

Feature or Bugfix

  • Bugfix

Purpose

When toc_object_entries = True the nesting of the objects in the toctree seems to done based on the scoping rules of the domain, instead of how the objects are documented in the input document. This PR tries to use the doctree to define the nesting instead.

Detail

The previous traversal of the doctree was done with .findall() which doesn't provide any path--from-root information when each element is yeilded. It therefore used memo_parents to store parent information, but it was indexed by domain-specific information.
I have kept the .findall(), but memo_parents is now indexed by desc nodes. As each desc may have multiple signatures, it will be the last one which gets the nested elements.
Example:

L1
==

.. py:class:: CL1a
              CL1b

	.. py:method:: f()

.. py:method:: CL1a.g()

.. py:method:: CL1b.g()

L2
--

.. py:class:: CL2a
              CL2b

	.. py:method:: f()

.. py:method:: CL2a.g()

.. py:method:: CL2b.g()

Before, the toctree became

- L1
  - CL1a
    - CL1a.g()
  - CL1b
    - CL1b.f()
    - CL1b.g()
 - L2
    - CL2a
      - CL2a.g()
    - CL2b
      - CL2b.f()
      - CL2b.g()

With this PR, the toctree corresponds to the document structure:

- L1
  - CL1a
  - CL1b
    - CL1b.f()
  - CL1a.g()
  - CL1b.g()
  - L2
    - CL2a
    - CL2b
      - CL2b.f()
    - CL2a.g()
    - CL2b.g()

Are there any tests for this? None seems to break with the change.

Relates

Fixes #12352.

@chrisjsewell
Copy link
Member

Are there any tests for this? None seems to break with the change.

Hey @jakobandersen cheers, but yes I feel we should look to add a MWE test that breaks on the current behaviour and is fixed by this change

@AA-Turner AA-Turner mentioned this pull request Jul 13, 2024
@AA-Turner AA-Turner merged commit e08f12f into sphinx-doc:master Jul 14, 2024
21 checks passed
@AA-Turner AA-Turner added this to the 7.4.0 milestone Jul 14, 2024
@jakobandersen
Copy link
Contributor Author

Thanks for making the test and merging!

@jakobandersen jakobandersen deleted the toctree-fix branch July 14, 2024 08:36
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 14, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

toc_object_entries uses language (Python) scoping instead of documentation scoping
3 participants