toc_object_entries uses language (Python) scoping instead of documentation scoping

[jakobandersen]

Describe the bug

The entries added by toc_object_entries for Python (and other domains?) seems to use the scoping of the language to nest the toc entries, instead of how they were declared in the document. E.g., if a nested class is declared after the class, then its entry is nested inside the class instead of appended.

How to Reproduce

E.g., with

.. py:currentmodule:: myMod
.. py:class:: MyClass

	.. py:method:: f()

.. py:class:: MyClass.MyNestedClass

I get the toc

- MyClass
  - MyClass.f()
  - MyClass.MyNestedClass

instead of

- MyClass
  - MyClass.f()
- MyClass.MyNestedClass

Environment Information

Tested with current master.

Sphinx extensions

No response

Additional context

Could the check at

sphinx/sphinx/environment/collectors/toctree.py

Line 146 in 88a54d8

if parents and parents in memo_parents:

be changed to check if the parent in the language is also the parent in the current toctree generation?

[electric-coder]

Being a directive shouldn't currentmodule also have an empty line and one level of nesting? Like this:

.. py:currentmodule:: myMod

    .. py:class:: MyClass

        .. py:method:: f()

    .. py:class:: MyClass.MyNestedClass

To get the nested class I'd rely only on reST scoping rules so it seems the most robust and language agnostic solution would be to put f() and MyNestedClass on the same level:

.. py:currentmodule:: myMod

    .. py:class:: MyClass

        .. py:method:: f()

        .. py:class:: MyNestedClass

---

However I think you're right that:

seems to use the scoping of the language to nest the toc entries, instead of how they were declared in the document.

If you want to document the nested class flattened on the same level as the containing class then the TOC should have given the desired result:

- MyClass
  - MyClass.f()
- MyClass.MyNestedClass 

[jakobandersen]

Being a directive shouldn't currentmodule also have an empty line and one level of nesting? Like this:

The currentmodule has no content, but simply sets the module. However, if you use module with content, then it's equivalent to the original example, and produces the wrong TOC as well.

To get the nested class I'd rely only on reST scoping rules so it seems the most robust and language agnostic solution would be to put f() and MyNestedClass on the same level:

Generally I agree that showing them nested is a good default. However, in the original use-case there are multiple nested classes and all involved classes are relatively large, making it desirable to separate them.