Docs as code#
Общее описание#
Документация как код (Docs as Code) - это подход к созданию, управлению и развертыванию документации, который основан на принципах и практиках разработки программного обеспечения.
Это означает следовать тем же рабочим процессам, что и команды разработчиков, и быть интегрированными в команду продукта. Это обеспечивает культуру, в которой писатели и разработчики чувствуют себя владельцами документации и работают вместе, чтобы сделать ее как можно лучше.
В этом подходе технический писатель использует те же инструменты, что и разработчики: документация как и код, хранится в системах контроля версий, автоматически проверяется на ошибки, один раздел документации можно переиспользовать в разных документах.
Этот подход способствует повышению качества документации и ее более эффективному сопровождению.
Схема ниже, показывает процесс разработки документации по технологии “docs-as-code” с использованием системы контроля версий Git, инструмента Sphinx для сборки документации, CI/CD Pipeline для автоматизации процесса сборки и публикации изменений, а также возможность получения документации в различных форматах для просмотра и распространения.
Технический писатель (TechWriter) редактирует документацию и вносит изменения в Git репозиторий (Git Repository).
После внесения изменений, пользователь выполняет коммит изменений в Git репозитории.
Когда пользователь выполняет push, запускается процесс CI/CD Pipeline (непрерывная интеграция/непрерывное развертывание).
В рамках CI/CD Pipeline выполняется: проверка изменений в репозитории, запуск линтеров (Linters) для проверки кода и стиля документации.
После успешного прохождения проверок, происходит сборка документации с использованием инструмента Sphinx.
Исходные файлы документации из репозитория Git клонируются и передаются в инструмент Sphinx для генерации документации.
Сформированные файлы документации в форматах docs, PDF и HTML сохраняются в соответствующих базах данных (Docs, PDF, HTML).
Технический писатель может просмотреть документацию (HTML) или скачать (Docs, PDF).
Ниже перечислены основные инструменты, которые можно использовать для реализации подхода “Docs as Code”:
Инструменты#
Языки разметки текстовых файлов#
С помощью языков разметки текстовых файлов можно создавать и форматировать документы. Зачем они нужны:
Простота и Читаемость: Языки разметки, такие как Markdown, предоставляют простой и интуитивно понятный синтаксис, который легко читать и понимать. Они освобождают авторов от необходимости работать с громоздкими тегами, что делает написание документации или форматирование текста более простым и приятным.
Структурирование контента: Языки разметки позволяют организовывать контент в разделы, заголовки, списки, таблицы и другие элементы. Это делает документацию или статьи более читабельными и легкими для навигации.
Переносимость и Платформонезависимость: Файлы, написанные на языках разметки, являются текстовыми файлами, которые могут быть легко перенесены между различными платформами и редакторами без потери форматирования.
Интеграция с Git и системами контроля версий: Языки разметки прекрасно сочетаются с системами контроля версий, такими как Git. Это позволяет отслеживать историю изменений и сотрудничать над документацией, как это делается с исходным кодом.
Дружественность для разработчиков: Многие языки разметки разработаны так, чтобы быть дружественными для разработчиков и обладать синтаксисом, более близким к коду. Это делает их более привлекательными для технической аудитории, так как они могут использовать знакомые концепции и средства.
Богатый функционал: Некоторые языки разметки, например, AsciiDoc, предлагают расширенные возможности, такие как вставка математических формул, ссылки на источники, дополнительные стили и т.д., что делает их более мощными для создания сложных документов.
Поддержка конвертации в другие форматы: Большинство языков разметки позволяют легко конвертировать документы в различные форматы, такие как HTML, PDF, DOCX и другие. Это упрощает публикацию и распространение документации.
В целом, языки разметки упрощают процесс создания и форматирования текстовых документов, делая их более организованными, читаемыми и легко управляемыми. Ниже приведены наиболее популярные языки разметки, которые можно использовать для создания документации:
Markdown: Простой и широко используемый язык разметки, который позволяет создавать легко читаемый и структурированный контент.
reStructuredText (RST): Другой популярный формат разметки, часто используемый в проектах Python и Sphinx.
AsciiDoc: Мощный язык разметки с расширенными возможностями, поддерживается различными инструментами.
HTML: Хотя это язык разметки для веб-страниц, некоторые инструменты также могут использовать его для написания документации.
reMarkable: Упрощенный язык разметки, основанный на Markdown, но с расширенными функциями.
Генераторы статичных сайтов#
Генераторы статических сайтов (SSGs) представляют собой инструменты, которые принимают исходный код или исходные файлы, такие как файлы разметки и шаблоны, и преобразуют их в статические HTML-страницы. Эти готовые HTML-страницы затем могут быть развернуты на веб-сервере и обслуживаться без необходимости в серверной обработке.
Вот несколько причин, почему генераторы статических сайтов полезны и зачем они нужны:
Производительность: Статические сайты не требуют серверной обработки или базы данных для генерации страниц при каждом запросе, что делает их очень быстрыми в загрузке и отклике. Это позволяет улучшить производительность сайта и уменьшить нагрузку на сервер.
Безопасность: Поскольку статические сайты не имеют серверной обработки, риск возникновения уязвимостей, связанных с серверной стороной, снижается. Это делает сайты более безопасными и менее подверженными атакам.
Простота развертывания: Статические сайты состоят из простых HTML-файлов, которые могут быть размещены на любом статическом хостинге или сервисе. Это упрощает процесс развертывания и управления сайтом.
Масштабируемость: Статические сайты хорошо масштабируются, так как они не требуют дополнительных ресурсов для обработки каждого запроса. Они могут легко справляться с большим количеством посетителей без необходимости в дополнительном оборудовании или инфраструктуре.
Простота версионирования и совместной работы: Использование генераторов статических сайтов позволяет хранить в системе контроля версий исходные файлы документации или сайта, что упрощает версионирование, сотрудничество и контроль изменений.
SEO-преимущества: Статические сайты обычно имеют простую структуру URL и легко оптимизируются для поисковых систем, что может положительно сказаться на SEO (поисковой оптимизации) сайта.
Экономия ресурсов: Статические сайты не требуют использования баз данных и серверных ресурсов для генерации страниц, что может сэкономить средства на хостинге.
SSGs становятся все более популярными благодаря своим преимуществам в производительности, безопасности и простоте развертывания. Они особенно полезны для сайтов документации и других проектов, которые не требуют сложной серверной логики. Ниже приведены наиболее популярные генераторы статичных сайтов, которые можно использовать для создания документации:
Jekyll: Один из наиболее популярных генераторов, написанный на Ruby, часто используется на GitHub Pages.
Hugo: Быстрый генератор, написанный на языке Go, отличается высокой производительностью.
Sphinx: Часто используется для создания документации Python, но также поддерживает другие языки разметки.
MkDocs: Простой и легкий генератор, использующий Markdown для создания документации.
Gatsby: Основанный на React, предназначен для создания быстрых и современных веб-сайтов.
Редакторы текстовых файлов#
Для редактирования языков разметки, кода и документации существует множество редакторов и интегрированных сред разработки (IDE). Вот некоторые из популярных редакторов и IDE, которые широко используются для работы с различными языками разметки и программирования:
Visual Studio Code (VS Code): Один из самых популярных и мощных редакторов, поддерживает множество языков программирования, а также разметку Markdown и другие форматы. Он легковесен и имеет огромное количество расширений, делая его отличным выбором для разработки и редактирования документации.
Atom: Еще один расширяемый редактор, разработанный GitHub. Поддерживает разметку Markdown и обладает множеством плагинов для работы с различными языками программирования.
Sublime Text: Очень быстрый и легкий редактор, также обладает поддержкой разметки Markdown и языков программирования.
Notepad++: Простой и бесплатный текстовый редактор, поддерживающий множество языков и форматов разметки.
Vim: Мощный и универсальный текстовый редактор, который работает из командной строки. Поддерживает множество языков разметки и программирования.
Emacs: Другой мощный и универсальный текстовый редактор с обширными возможностями, поддерживающий разметку и программирование.
IntelliJ IDEA: Широко используется для разработки на Java, но также поддерживает различные языки разметки и другие языки программирования.
PyCharm: Специализированная IDE для разработки на Python, также поддерживает разметку Markdown и другие языки.
Eclipse: Еще одна популярная IDE, которая часто используется для разработки Java-приложений, но имеет поддержку различных языков и плагинов.
Rider: IDE для разработки на платформе .NET и C#, с поддержкой других языков и разметки.
Конечный выбор редактора или IDE зависит от ваших предпочтений, языков программирования, которые вы используете, и особенностей вашего проекта. Каждый из перечисленных инструментов обладает своими преимуществами и набором функций, поэтому рекомендуется попробовать несколько из них и выбрать тот, который лучше всего соответствует вашим потребностям и стилю работы.
Системы контроля версий#
Git: Распределенная система контроля версий, одна из наиболее популярных и широко используемых.
Subversion (SVN): Централизованная система контроля версий, которая также широко применяется.
Mercurial: Еще одна распределенная система контроля версий, похожая на Git.
Perforce (Helix Core): Популярная система контроля версий, часто используемая в больших предприятиях.
Bitbucket: Хотя это не сама система контроля версий, но он предоставляет возможность хостинга Git и Mercurial репозиториев.
Линтеры#
Линтер (англ. “linter” от “lint”) - это инструмент программной проверки и анализа исходного кода или текста с целью выявления стилистических ошибок, потенциальных проблем или соблюдения определенных правил программирования или написания текстов.
Линтеры используются для автоматизации процесса анализа кода или текста, что позволяет выявлять такие проблемы, как синтаксические ошибки, стилистические несоответствия, неиспользуемый код, использование устаревших конструкций и другие проблемы, которые могут быть пропущены при обычном просмотре кода вручную.
Линтеры — это незаменимые инструменты если вы работаете по docs-as-code, рассмотрим несколько популярных линтеров для различных форматов.
Для чего следует использовать линтеры?#
Линтеры для проверки кода: Линтеры для кода широко используются в разработке программного обеспечения. Они позволяют обнаруживать синтаксические ошибки, стилистические несоответствия и потенциальные проблемы, которые могут пропустить обычные средства разработки. Такие инструменты как ESLint для JavaScript, Pylint для Python и RuboCop для Ruby стали неотъемлемой частью проектов различных масштабов.
Линтеры для документации: Качественная документация имеет важное значение для успешного проекта. Линтеры для документации, такие как MkDocs Linter для MkDocs или markdownlint для Markdown, помогают выявить ошибки форматирования, отсутствующие заголовки, неправильные ссылки и другие проблемы. Они значительно облегчают работу технических писателей и обеспечивают согласованность стиля и формата документации.
Улучшение рабочего процесса: Использование линтеров в проекте способствует улучшению рабочего процесса команды разработчиков и авторов документации. Автоматический анализ и проверка кода и текста позволяют рано выявлять проблемы и исправлять их, что снижает вероятность появления ошибок в продакшене и ускоряет процесс разработки.
Общие#
MkDocs Linter: Это плагин для MkDocs, который позволяет проверять структуру документации, а также форматирование Markdown. Он поможет обнаруживать проблемы в документации, такие как отсутствие заголовков, несоответствие стиля и т.д.
Dockerfile Linter: Документация для контейнеров Docker часто пишется в формате Markdown. Dockerfile Linter позволяет автоматически проверять файлы Dockerfile и документацию, связанную с контейнерами.
Write-Good: Это инструмент для проверки текста на соответствие хорошим практикам в документации. Он предназначен для поиска некорректных или непонятных фраз, например, использование длинных предложений или криво сформулированных фраз.
Prospector: На самом деле Prospector - это инструмент для анализа кода на языке Python, но он также может использоваться для анализа документации, написанной на Python в формате Sphinx. Prospector включает в себя плагин pep257, который обнаруживает стиль и форматирование docstrings в коде Python.
Vale: Vale предоставляет возможность создавать собственные наборы правил (style guides) для проверки документации на соответствие стилю, терминологии и другим правилам. Он поддерживает Markdown, AsciiDoc и другие форматы документации.
GitHub Super Linter: Это инструмент от GitHub, который объединяет несколько линтеров (в том числе для Markdown и YAML) и предоставляет возможность запуска всех проверок сразу. Он может использоваться для проверки документации, хранящейся в репозитории на GitHub.
Linter для Sphinx#
Sphinx Lint: Это инструмент командной строки, который предназначен для анализа документации Sphinx и выявления различных проблем, таких как неправильные ссылки, отсутствующие заголовки, ошибки форматирования и другие структурные ошибки.
sphinxcontrib-spelling: Этот плагин позволяет проверять правописание в документации Sphinx. Он использует словарь слов и проверяет документацию на наличие опечаток и неправильных слов.
sphinxcontrib-textstyle: Этот плагин проверяет текстовый стиль документации Sphinx, включая стилистику предложений и использование заголовков.
rstcheck: Хотя это не специфический для Sphinx линтер, rstcheck может использоваться для анализа документации в формате reStructuredText, который используется в Sphinx. Он проверяет документацию на синтаксические ошибки и предупреждения.
Sphinx-pretty-searchresults: Этот плагин для Sphinx предназначен для улучшения стиля вывода поисковых результатов, которые генерирует Sphinx.
Linter для AsciiDoc#
Asciidoctor: Asciidoctor - это инструмент для преобразования AsciiDoc в различные форматы, такие как HTML, PDF, DocBook и другие. Он также предоставляет возможность выполнения проверок на соответствие стилю и наличие ошибок в документации.
Asciidoctor-diagram: Это плагин для Asciidoctor, который добавляет поддержку для вставки диаграмм и рисунков в AsciiDoc-документацию. Он также может быть использован для проверки синтаксиса диаграмм.
Asciidoctor-lint: Это расширение для Asciidoctor, которое позволяет выполнять дополнительные проверки и анализ документации на наличие ошибок и предупреждений.
TextLint: TextLint - это универсальный линтер текста, который поддерживает различные форматы, включая AsciiDoc. С помощью подходящего плагина он может быть настроен для анализа AsciiDoc-документов.
AsciidocFX: Это редактор и просмотрщик AsciiDoc, который также содержит функционал проверки документации на соответствие правилам стиля.
Linter для Markdown#
markdownlint: Это популярный линтер для Markdown, который обнаруживает и предупреждает о различных проблемах в документации. Он проверяет синтаксис, стиль, правописание и другие аспекты Markdown-файлов.
remark-lint: Еще один мощный линтер для Markdown, основанный на инструменте remark. Он предоставляет гибкие настройки и расширения для анализа Markdown-файлов.
markdown-spellcheck: Это инструмент для проверки орфографии в файлах Markdown. Он обнаруживает неправильные слова и предлагает исправления.
textlint: TextLint - это универсальный линтер текста, который поддерживает различные форматы, включая Markdown. С помощью соответствующего плагина он может быть настроен для анализа Markdown-документов.
Полезные ссылки#
https://jamstack.org/generators/ - Список генераторов статических сайтов для сайтов Jamstack
https://starkovden.github.io/Static-site-generators.html - Варианты хостинга и развертывания статичных сайтов
Видео#
https://youtu.be/bjUkCCn2VoU - Automate Python Documentation | Use Sphinx + GitHub actions to publish documentation