Mangled section order by add_domain_to_toctree

[jakobandersen]

The automatic toctree entries from domain directives is usually nice, but I encountered an odd case. Consider

Big Header
##########

.. py:class:: MyClass

Sub-header
==========

.. py:function:: doStuff()

then I get

The structure I would expect is

• Big Header
  • MyClass
  • Sub-header
    • doStuff

Minimal working example: autoapiTest.tar.gz

[AWhetter]

Really we should restrict the addition of toctree nodes to only where the documentation is generated.
But the fact that it edits the toctree in this way is also an issue.

This functionality exists to overcome what I see as a shortcoming of Sphinx, and ideally Sphinx would be capable of adding domain nodes to the toctree itself. I've started work on this in sphinx-doc/sphinx#6316, but it might take a while.

[jakobandersen]

This functionality exists to overcome what I see as a shortcoming of Sphinx, and ideally Sphinx would be capable of adding domain nodes to the toctree itself. I've started work on this in sphinx-doc/sphinx#6316, but it might take a while.

I completely agree, and the interface you suggest there seems nice to me. Though, I don't know much about the toctree part of Sphinx, so I can't say what the best implementation strategy is.

[AWhetter]

Sphinx is now capable of adding domain objects to the toctree itself. Therefore add_domain_to_toctree was removed from AutoAPI and this issue is no longer relevant.