Я считаю неправильным включать reST структурные элементы в строку документации, а именно Разделы (заголовки) и Переходы (Sphinx должен выдать предупреждение, если вы попытаетесь). Не путайте первое с разделами строки документации . Оба называются разделами , но на этом сходство заканчивается.
Потому что, если вы хотите включить данный модуль или класс в два разных файла .rst, используя autodoc директивы , фиксированные заголовки (структурный элемент) внутри строки документации могут не совпадать с другой иерархией заголовков в файлах .rst.
Это создаст структурное ограничение, иерархия заголовков файлов .rst будет зависеть от размещение в нем ваших autodoc директив. Концептуально, я думаю, что управление структурой должно зависеть только от файла .rst.
Плюс, стиль оформления раздела , который однажды встречается, определяет уровень заголовка, поэтому разные размещения вашего autodoc директивы в конечном итоге получат контроль над структурой .rst. (И давайте не будем забывать, что если ваш вывод - HTML, вы будете ограничены 6 уровнями заголовков, поэтому их использование в строках документации еще больше ограничит ваши структурные параметры в .rst ...)
Как документальный фактор учитывается в этом уравнении? (упоминается OP в комментариях.)
Не беспокойтесь о документах !! Обычному разработчику Python нужен только Sphinx (что влечет за собой reST ) для написания хорошей документации. Использование документации будет заключаться в написании дополнительных расширений Sphinx, но для большинства применений стабильные расширения / директивы уже предусмотрены.