но надо посмотреть насколько там сложная хтмл-ка на выходе

Спасибо, попробовал. Работает также плохо как openapi-generator, да и по устройстуу очень подозрительно на него похож.
Основная проблема: в выводе отсутствуют части спецификации.
ReDoc выводит результат корректно.

Для каких задач вы используете sphinx-doc?

Командная документация, документация внутренних библиотек, документация сервисов

Пользовательская документация на 10 языках

Можно ли при помощи этого инструмента делать документацию для партнеров с выводом в PDF?
С форматированными текстами, схемами-диаграммами, картинками, таблицами?

Давно собираюсь сделать демо, всё не доходят руки )

А так да. Диаграммы можно в PlantUML описывать.

С какими IDE вы работаете для написания и превью документов в sphinx/rst?

PyCharm

Там сразу консоль под рукой и есть плагин с подсветкой синтаксиса

Live preview нет, но и не нужно

Спасибо, попробуем у себя sphinx-doc.

И все же, есть у кого-нибудь опыт реальной работы с asciidoctor, можете рассказать про ограничения этого инструмента?

Да, мы делаем с помощью latex шаблона

1. Мы используем https://github.com/Swagger2Markup (о нем писала @Lananovikova), но в git'е не заявлено поддержки OpenAPI 3.0 и в эксперементах были случаи, с которыми Swagger2Markup не справлялся. Я не вижу проблем, чтобы написать свой конвертор в Asciidoc или rst или в любой текстовый (даже нетекстовый) markup, но swagger2markup в реальных задачах пока не подводил.
2. Получаемый файл прекрасно конвертируется и в html, и в pdf. Но для pdf нужна цепочка через docbook-xsl (!!! ни в коем случае не родной конвертер). Не вдаваясь в подробности проще всего скачать https://www.asciidocfx.com/ (уродский, но вполне работающий редактро asciidoctor) и вот этими файлами https://github.com/CourseOrchestra/course-doc/tree/master/docbook-xsl-report заместить те, которые установил AsciidocFX. Кнопочка "сохранить в pdf" теперь будет делать то, что нужно
3. Обычно мы вставляем спецификацию Swagger в более общий документ (как раздел или приложение). Что, что, а это Asciidoctor делает хорошо.
4. Включение диаграмм, рисунков, чего угодно.. проблемой не является

Да, забыл. Генератором статистических сайтов мы не пользуемся. Но, говорят, jekyll хорош. Недавно попробовали  вести исходники документации на git'е и использовать станадртный travis-скрипт, который публикует все это в github.io. Очень удобно получается (https://github.com/CourseOrchestra/celesta/tree/dev/celesta-documentation/src/main/asciidoc), а сам travis-скрипт здесь https://github.com/CourseOrchestra/celesta/blob/dev/.travis.yml

А у меня пришел сеошник и потребовал переименовать урлы в транслит :(

Vot-takoy-translit?

А почему именно так лучше, он не объяснил? Я бы тоже хотел узнать об этом.