Тег: #sphinx — Hacker News Digest

I Prefer RST to Markdown (2024) (buttondown.com)

Markdown = лёгкая обёртка HTML, rST = промежуточное дерево документа.
В Markdown картинка: ![alt](img.jpg) → прямое преобразование в <img>.
В rST: .. image:: img.jpg :alt: alt → регистрируется обработчик, возвращает объект-узел, который потом рендерится нужным бэкендом.
rST расширяем: добавил .. figure::, подключил обработчик — готово.
Можно трансформировать дерево до вывода: перенос решений упражнений в конец книги, генерация ссылок, разные стили для HTML, PDF, EPUB.
Пример: .. exercise:: Fizzbuzz и .. solution:: собираются в одном месте, но при сборке перемещаются в solutionlist, связываются ссылками, в EPUB открываются всплывающими сносками, в LaTeX — через answers.

by shlomo_z • 17 августа 2025 г. в 19:51 • 91 points

RST мощнее и расширяемее, но синтаксис вызывает отторжение и сложен для новичков.
Markdown читается и пишется проще, поэтому стал де-факто стандартом, но не хватает возможностей для больших документов.
MyST, Asciidoc, Djot и Typst предлагают компромисс между простотой и функциональностью, но пока уступают Markdown в распространённости инструментов.
Парсеры RST доступны в основном на Python, а у Markdown — «каждый реализует свой диалект».
Для книг и сложной документации RST + Sphinx выигрывают за счёт автогенерации HTML/PDF/EPUB, глоссариев и индексов.