Краткий (очень) разбор преимуществ reStructuredText vs Markdown для написания технической документации

https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/

#reStructuredText #markdown #article #en

MyST - Markedly Structured Text — для любителей Sphinx и Markdown и "нелюбителей" reStructuredText.

MyST позволяет писать документацию Sphinx полностью в Markdown. Этот парсер предоставляет маркдаун-эквивалент синтаксиста reStructuredText.

Главные особенности MyST:

- Парсер Markdown для Сфинкса. Вы можете написать всю документацию в Sphinx в Markdown.

- Вызов директив и ролей Sphinx из Markdown, что позволит вам расширить ваш документ с помощью расширений Sphinx.

- Расширенный синтаксис Markdown для полезных функций rST, таких как комментарии к строкам и сноски.

- Сфинкс-независимый анализатор разметки MyST, который может быть расширен для добавления новых функций в MyST.

- Надстройка над CommonMark-флейвором md. Любая разметка CommonMark (например, разметка Jupyter Notebook) изначально поддерживается парсером MyST.

Перевод корявенький, но суть, я думаю, ясна

#tool #markdown #reStructuredText #SSG

👅 Языки:

#ru | #en

👷 Карьера:

#career — советы и всемозможные статьи о карьере техписателя
#conference — техписательские конференции, их записи и заметки
#resources — ресурс для саморазвития
#article — полезная статья, которая учит чему-то клёвому, что позволит стать более лучшим писателем
#vacancy — интересная вакансия или что-то связанное с наймом
#video — видео, видос, видосичек, видосюлька. И подкасты!
#book — книга/хендбук
#courses — курсы, программы для технических писателей

🛠 Технологии:

#tool — полезная утилита/приложение
#changelog — все о чейнджлогах, примеры, правила
#markdown — все о языке разметки Markdown
#reStructuredText — все о языке разметки reStructuredText
#asciidoc — все о языке разметки asciidoc
#LaTeX — все систему набора и вёрстки и язык разметки LaTeX
#ide — среды разработки и все что с ними связано
#vscode — все о Visual Studio Code, настройка, плагины, хитрости
#SSG — JAMStack, генераторы статических сайтов, Hugo, Jekyll, Antora, etc.
#testthedocs — тестирование документации, линтинг
#API — про документирование API, примеры, лайфхаки, подсказки
#diagram — про диаграммы (много про diagrams as a code), mermaid, UML
#screenshot — все про скриншоты, утилиты, сервисы и красивенькие фотоснимки экрана
#ai — про GPT, GitHub Copilot и прочее, где ИИ помогает нам писать

🧺 Общее:

#tonevoice — о правилах общения в документации
#language — что-то конкретно о языке, в основном английский
#legal — юридическая документация, лицензии
#styleguide — все о стилях и правилах
#DocsAsCode — все про подход к документации как к коду
#example — примеры документации (хорошие и плохие)
#uiux — интерфейсы, текст в интерфейсах, пользовательский опыт
#knowledgemanagement — менеджмент знаний, хранилища, тулзы, техники, советы и наблюдения
#versioning — про версионирование
#accessibility — все об аксессебилити в документации
#checklist — чеклист/шпаргалка
#vintage — винтажная документация, старые компьютеры, софт, техника, игры
#visual — про визуальную составляющую документации
#metrics — все о метриках документации
#random — что-то совсем косвенно относящееся к техписательству, юморески

Предлагайте новые хэштеги в комментариях!