Docs as code

Docs as code - концепция подготовки документации наравне с программным кодом. Она не исключает использования визуальных (WYSWYG)-решений. Т.е. визуально подготовка документации может не отличаться от работы в Google Docs например. Сам текст документации размечен с помощью языков разметки Markdown или reStructuredText. Либо других иных (непринципиально).

Критерии DaC[править]

Как критерии концепции описываются следующие моменты^[1]:

Использование тикет-системы для работы с документацией
Хранение текстов документации в системе контроля версий (например, в Git)
Человекопонятная разметка текста (Markdown, reStructuredText, Asciidoc) - обычно не XML/SGML
Code Reviews
Automated Tests

Решения[править]

Эти решения для подготовки документации относятся к категории "SSG" - static site generators (англ. Википедия). Поскольку в результате их работы появляются неизменяемые файлы. И сам процесс поход на компиляцию программы из исходного кода.

Sphinx. Используется для Read the docs - см. ниже.
Docusaurus - использует node.js, для кастомизации React
Hugo с системой шаблонизации Go. пример (Cloudflare)
Jekyll с системой шаблонизации liquid. Используется в GitHub Pages.
Doxygen - извлекает текст из программного кода и генерит документацию. Ряд платформ имеют встроенные такие функции, например, dart doc
Antora пример, 2
Foliant (для генерации pdf and docx, использует Pandoc или md-to-pdf, для веб-сайтов MkDocs, Aglio или Slate.)
Material for MkDocs

Готовые к использованию реализации

Эти реализация не требуют установки и можно пользоваться, выполнив инструкции по быстрому старту. Функционал можно увидеть в бесплатной версии.

Read the Docs готовое веб-решение (использован Sphinx или [[w:en:MkDocs]MkDocs|])
GitHub Pages^[2] - готовое решение от Github, штатно поддерживает Jekyll, но через Github actions можно подключить другие SSG - Hugo, Gatsby, Next.js, Nuxt.js, MkDocs, VuePress, Docusaurus.
Netlify - из коробки готов к использованию Hugo. Тема docsy (от Google) для Hugo имеет документацию на Netlify.

Кто какую SSG использует[править]

Linux Mint использует Read the Docs^[3]
Dart использует Eleventy ^[4], до него использовался Jekyll^[5].
Spring использует ASCIIDoctor ^[6]

См. также[править]

w:en:Documentation_generator - программные инструменты, генерящие документацию для конечных пользователей или для разработчиков (описание АПИ)

Ссылки[править]

Примечания[править]

[1] ttps://www.writethedocs.org/guide/docs-as-code/

[2] ttps://pages.github.com/

[3] ttps://linuxmint-user-guide.readthedocs.io/en/latest/lost-password.html

[4] ttps://docs.flutter.dev/cookbook/networking/authenticated-requests

[5] ttps://github.com/flutter/website/issues/10203

[6] ttps://docs.spring.io/spring-framework/reference/core/resources.html

[1]

[2]

[3]

[4]

[5]

[6]