Especially in Python applications I tend to try to write code that you can read top to bottom like a text and figure out what it does. This is largely destroyed

Especially in Python applications I tend to try to write code that you can read top to bottom like a text and figure out what it does. This is largely destroyed by using an external documentation tool (whether that's Doxygen or Sphinx is irrelevant), because those only extract a very tiny and fixed amount of information from the code. Some docgens even reorder entities alphabetically (by default), which is basically heresy. I think it would be very interesting if e.g. Sphinx were able to generate pages where the highlighted and crossreferenced code is interleaved with the processed markup from those parts it extracts today (docstrings etc.). Heck, even being able to just tell it to only generate the source code pages and crossref to those instead would be better for documenting applications.