Sphinx 101: как быстро и легко оформить свою документацию, используя методологию docs-as-code#
Всем привет, меня зовут Михаил, я технический писатель в компании Мобильные решения для строительства. Работу я начал в 2020 году и уже успел создать пользовательскую инструкцию для нашего продукта и сейчас работаю над документацией для прикладных решений.
Я решил поделиться своим опытом работы по методологии docs-as-code и рассказать самый быстрый способ создания статического сайта для документации.
После прочтения этой статьи целиком вы поймёте, насколько легко сейчас создать красивую и удобную документацию. С этой задачей справится копирайтер без глубоких технических знаний.
Docs-as-code (Documentation as Code) — это методолгия, при которой к документации относятся, как к коду. То есть используются похожие инструменты и методы, что и с кодом:
Система поиска ошибок.
Система контроля версий (Git).
Облегчённый язык разметки (Markdown, reStructuredText, Asciidoc и так далее).
Ревью кода.
Автоматизированные тесты.
В данной статье мы рассмотрим, как можно при помощи генератора статической документации (Sphinx) создать и выложить простой и красивый сайт с вашей инструкцией.
В конце статьи я подскажу несколько дополнений к голому Sphinx, которые помогут с визуализацией медиа-файлов.