Викиучебник

Docs as code

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

Критерии DaC

править

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

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

SSG-решения

править

Эти решения для подготовки документации относятся к категории "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.
  • Gitlab имеет сервис Gitlag Pages аналогичный тому что на Github

Кто какую SSG использует

править
  • Fedora Linux использует Antora[3]
  • Linux Mint использует Read the Docs[4],[5]
  • Dart использует Eleventy [6], до него использовался Jekyll[7].
  • Spring использует ASCIIDoctor [8],[9]
  • GitLab для свой документации - использует Nanoc[10],[11]

Какие SSG из коробки поддерживают Asciidoc-форматирование

править
  • Antora (Maintained by lead contributors to the Asciidoctor project)
  • Список[12]

См. также

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

Ссылки

править

Примечания

править
  1. ↑ https://www.writethedocs.org/guide/docs-as-code/
  2. ↑ https://pages.github.com/
  3. ↑ contributors-guide
  4. ↑ https://linuxmint-user-guide.readthedocs.io/en/latest/lost-password.html
  5. ↑ Github
  6. ↑ https://docs.flutter.dev/cookbook/networking/authenticated-requests
  7. ↑ https://github.com/flutter/website/issues/10203
  8. ↑ https://docs.spring.io/spring-framework/reference/core/resources.html
  9. ↑ Github
  10. ↑ docs.gitlab.com
  11. ↑ https://gitlab.com/gitlab-org/gitlab-docs
  12. ↑ https://gist.github.com/briandominick/e5754cc8438dd9503d936ef65fffbb2d
Источник — https://ru.wikibooks.org/w/index.php?title=Docs_as_code&oldid=241331