readthedocs/sphinx-autoapi

Mangled section order by add_domain_to_toctree

jakobandersen opened this issue · 3 comments

jakobandersen commented

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
autoapi
The structure I would expect is

  • Big Header
    • MyClass
    • Sub-header
      • doStuff

Minimal working example: autoapiTest.tar.gz

AWhetter commented

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 commented

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 commented

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.