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

[jakobandersen]

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]

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

[jakobandersen]

Thanks for making the test and merging!