I'm actually not entirely sure if it's the case for Python renderer, but in my own renderer I ran into the issue that if the docstring contains a # Markdown Heading, it's not adjusted according to the current heading_level, so in the nav it'll just appear as a topmost item regardless of what's happening around it.

I'm currently looking into a solution.