можно ли автоматически сформировать документацию на основе комментариев к программному коду
Автоматизация оформления документации
Работая над проектами связанными с авионикой мне потребовалось оформить несколько комплектов документации с полным описанием проекта. Также следовало учитывать требования многих ГОСТов на оформление и на содержание документации, таких как ЕСПД, КТ-178B и других.
Объем документирования очень большой. Данные во всех документах связаны друг с другом, поэтому при изменении проекта (например добавления нового требования), приходится редактировать практически все документы. Плюс к этому можно где-то ошибиться или забыть поправить, что приводит к ошибкам в документации.
Далее в статье я расскажу как я решил эту проблему.
Архитектура генератора документации
Поэтому было решено использовать автоматизированные средства, которые создают все документы, используя данные из первичных документов — таблиц в формате CSV, XML документов. При любых изменениях в проекте — можно запустить заново генерацию комплекта документации.
Таблицы в формате CSV удобно редактировать в табличном процессоре. Данные о проекте (текущую версию, наименование, совместимое оборудование) хранил в формате XML.
Описание реализации требований уже содержится в doxygen комментариях к исходному коду. Doxygen специально для таких случаев может генерировать документацию в формате XML.
Генератор документации на основе шаблонов документов создает LaTeX документы, которые уже в PDF формате передаются заказчику.
Генератор документации
Для реализации такой системы создания документации мне потребовалась утилита обработки шаблонов и скрипт сборки.
Ключевой элемент системы — утилита обработки шаблонов документов.
Утилита обработки шаблонов
Или установить утилиту можно с помощью команды:
В шаблонах содержится информация — данные из каких внешних источников ему нужны. Утилита во время обработки шаблона подгружает необходимые данные, и использует их при заполнении шаблона данными.
В утилиту передается файл шаблона и путь до результирующего файла. Пути до источников данных в программу не передаются, так как они все определены в шаблоне, и один шаблон может использовать множество разных источников данных.
Education Ecosystem Blog
The Education Ecosystem Blog is a hub for in-depth development blogs and new technology announcements written by professional software engineers in the Education Ecosystem network
Featured in
10 инструментов для безупречного документирования кода
Многие программисты не любят это дело и пытаются всячески избежать этой работы всеми доступными способами. Отсутсвие документации кода приводит к плохой его читаемости и к сложному техническому обслуживанию для других членов команды.
Документация кода отличается от проектной документации, так как она в основном фокусируется на том как работает система. Несмотря на то, есть несколько причин для написания документации, многие программисты, как правило, игнорируют это. Ниже я собрал ряд причин по которым все таки стоит писать документацию для своего кода:
Даже с учетом всех вышеперечисленных преимуществ, документирование, в целом, является трудоемким процессом. Для того, чтобы обеспечить более быстрый процесс подготовки документации и последовательности стилей, вам стот использовать специальные инструменты.
Эти инструменты помогут вам с документированием кода и в целом помогут стать на ступеньку выше. Давайте начнем!
DOXYGEN
Doxygen является отличным инструментом для генерации документации из исходного кода. Инструмент нацелен на документирование программного обеспечения, написанного на языке C++, однако на самом деле данная система поддерживает гораздо большое число других языков, таких как: C, Objective-C, C#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, и частично D. С помощью Doxygen, вы можете создать онлайн HTML документацию. Doxygen — консольная программа в духе классической Unix. Она работает подобно компилятору, анализируя исходные тексты и создавая документацию.
Самым большим преимуществом использования Doxygen является то, что вы будете иметь последовательность всей документации исходного кода. Она также может помочь вам создавать структуру кода с использованием недокументированных исходных файлов. Все, что вам нужно сделать, это настроить его соответствующим образом.
SPHINX
Sphinx это популярный инструмент позволяющий создавать текстовые документы и преобразовывать их в различные форматы. Это удобно при использовании систем управления версиями, предназначенных для отслеживания изменений. Он доступен по лицензии BSD и поддерживает несколько языков программирования, таких как Python, C и C++. Он может быть использован как для проектной документации так и для документации кода. Sphinx избавляет от рутинных действий и предлагает автоматическую функциональность для решения типовых проблем, например, индексирования заголовков и специального выделения кода (например, при включении в документ фрагментов кода) с соответствующим выделением синтаксиса.
PANDOC
Кроме того, он предлагает несколько расширений синтаксиса разметки, в том числе списки определений, таблицы, сноски и т.д. Полный спискок поддерживаемых расширений и форматов вы можете найти на официальной странице.
DR. EXPLAIN
Frontend разработка также, в определенной степени, требует документирования. Создавать документацию как для обычных, так и онлайн-приложений, написанных на любом языке программирования, в любой среде разработки, с применением любого фреймворка поможет DR. EXPLAIN. Он фильтрует ключевые элементы интерфейса, а затем извлекает связанные с ним мета данные. После этого, вы можете изменить полученную информацию, чтобы быстро создать документацию интерфейса.
LATEX
LaTex является де-факто стандартом для документирования научных проектов. Тем не менее, он также может быть использован для других типов проектов, в том числе кода и проектной документации. Готовя свой документ, автор указывает логическую структуру текста (разбивая его на главы, разделы, таблицы, изображения) и позволяет LaTeX’у заботиться о том, как изобразить его.
MARKDOWN
Markdown, творение Джона Грубера, очень простой и изящный синтаксис разметки текста, который поможет вам писать качественный код и документации. С технической точки зрения Markdown является инструментом преобразования текста в HTML для веб-писателей, но в равной степени он может быть использован и для документирования. Как разработчик, вы можете написать документацию в Markdown, а затем использовать Pandoc, чтобы преобразовать его в любой формат, который вам нужен.
GHOSTDOC
GhostDoc это расширение для Visual Studio, с помощью которого вы можете легко генерировать комментарии документа XML. Инструмент генерирует комментарии на основе нескольких факторов, в том числе имя, параметры, контекстную информацию, типы и т.д.
NATURAL DOCS
Natural Docs это еще один инструмент с открытым исходным кодом, который работает со многими языками программирования. Он поможет вам автоматизировать генерацию документации кода и преобразовать его в формат HTML. В настоящее время NATURAL DOCS поддерживает 19 языков программирования, среди них Python, C ++, PL / SQL, Actionscript и т.д.
PHPDOCUMENTOR
Если вы PHP разработчик и хотите сгенерировать документацию кода из исходного кода, стоит рассмотреть PhpDocumentor. В основе работы системы лежит парсинг логической структуры PHP кода (классы, функции, переменные, константы) и привязка к ней комментариев, написанных по определенным стандартам. Инструмент также может помочь вам генерировать отчеты и графики и повысить общее качество кода.
LIVEEDU.TV
Как стриминговая платформа может помочь в документировании кода? Вы можете транслировать или хранить проектную работу непосредственно на Livecoding. Вы будете иметь возможность легко открыть доступ к важным разделам проекта для членов вашей команды. Несколько преимуществ использования видео в качестве инструмента для документирования кода. Некоторые из них приведены ниже:
Дамиан Вольф расскрывает данную тему боле подробно в статье “Why Developers Write Horrible Documentation and How to Solve It”.
Сегодня мы ознакомились с 10 инструментами для упрощения документирования кода. Следует отметить, что инструменты, упомянутые выше, действуют как дополнения к процессу документирования.
Документирование кодовой базы. Зачем и как?
Введение
Недавно, на одном из митингов моей команды, была поднята проблема отсутствия документации внутри кода. Было решено назначить ответственного за ведение документации. Нужно было найти подходящие инструменты документирования, определить стиль и регламент, представить решение команде. Я решил, что возьму эту задачу на себя, так как для меня это особенно важный вопрос. Мне, как новому сотруднику, было довольно тяжело разобраться в уже существующем коде без документации, и упустить возможность повлиять на ее появление я просто не мог. В итоге, в процессе определения стандарта для нашей команды и появилась эта статья. Я подумал о том, здесь присутствуют довольно интересные мысли, поэтому решил поделиться ими здесь.
Дисклеймер
Так как я С++ разработчик, то и документирование кода я рассматриваю как документирование кода С++. Когда я говорю код, функция, метод или класс, я подразумеваю код, функцию, метод или класс на С++.
Зачем?
Здесь я приведу пару пунктов формата вопрос-ответ. Это те вопросы, которые я задавал себе сам и слышал от своих коллег, когда вставал вопрос документирования кода.
«Все и так знают наш код»
Это утверждение справедливо для разработчиков с большим опытом работы в компании, но никак не для тех, кто только включается в проект. Чем больше документации встретит новичок в коде, тем быстрее он сможет включиться в работу. 10 минут чтения документации лучше, чем 2 часа отладки кода.
«Этот код прост и не нуждается в документации»
Если такая мысль пришла вам в голову, обдумайте ее еще раз. Если подумать еще не помогло, посоветуйтесь со своими коллегами. Если ваш код не вызвал вопросов при одном только взгляде на него, то, возможно, комментирование кода действительно излишне (но это не точно). Этот пункт будет подробнее обсуждаться далее.
«Этим кодом больше никто пользоваться не будет»
Это неправда. Не использоваться он будет до поры до времени. В моей практике были моменты, когда я реализовывал то, что уже есть в нашей кодовой базе. Отсутствие документации и, соответственно, привычки искать существующие решения в ней, привели меня к дубликации кода.
Общие советы документирования
Приведите пример использования вашего кода
Оставьте названия функций/методов/классов, ткните в место, где используется ваш код. Если вы использовали какое-то популярное решение (паттерн), оставьте ссылку на материал по этой теме. Это поможет быстрее сориентироваться в коде. Понятно, что поиск в IDE даст вам ту же информацию, но иногда он бывает долгий, плюс таким образом вы сможете особенно выделить то место, где использование вашего кода продемонстрировано максимально явно.
Если решение нетривиально, расскажите о причинах такого решения
Почему использовано именно такое решение? Порой приходится много времени заниматься отладкой и изучением кода, чтобы понять, почему коллега выбрал именно такой подход. Краткий ответ на вопросы зачем и почему сэкономит много времени. Данный пункт переплетается с первым.
Постарайтесь найти середину между отсутствием документации и документированием каждой строки
Не нужно писать целую поэму для метода, из названия которого понятно, что он делает (я надеюсь, что название соответствует тому, что он делает). Также не стоит думать, что, например, простой класс не нуждается в подробной документации. Здесь важно найти золотую середину.
Не пересказывайте код
Не превращайте ваши комментарии в это
Пример того, как делать не надо
Не забывайте о поддержке документации IDE
Сейчас почти все IDE способны выводить описание класса/метода/функции при взаимодействии с ним (наведение мыши, комбинация клавиш), если описание оформлено в нужном формате. Пишите документацию так, чтобы (1) IDE смогла ее «подхватить», (2) можно было обойтись чтением документации и избежать необходимости открывать код с целью его изучения.
Дайте описание поведения вашей функции/метода в случае ошибки
Что вернет ваш код? Возможны ли исключения и какие? Если функция бросает слишком много исключений, возможно не стоит перечислять их все.
Помните о том, что ваши комментарии в будущем будут читать другие люди, в том числе и вы
Не пишите документацию ради документации, пишите ее ради облегчения работы своей команды. Задайте себе вопрос: пойму ли я, что делает этот код, через месяц, посмотреть на комментарии? Для более честного ответа, попросите ответить на этот вопрос своих коллег.
Не забывайте об актуальности документации
Неактуальная информация уже неактуальна хуже ее отсутствия.
Вопросы о грамотности, удобстве, понятности документации и прочие популярные я опускаю с надеждой на то, что такие вещи для читателя само собой разумеющееся.
Документирование можно вести в стандарте JavaDoc. Это удобный формат, который знаком многим IDE и поддерживается Doxygenом. Плюсом для нас было то, что он уже частично используется в нашем проекте, и IDE, в которых мы работаем (CLion, QtCreator, VisualStudio) прямо поддерживают генерацию комментариев в этом стандарте и их отображение.
Далее будут описаны инструменты документации и некоторые правила, которые мы приняли в своей команде.
Многострочные и однострочные комментарии
Doxygen поддерживает много видов комментариев. Для нашей команды я выделил такие:
Хочу обратить внимание, что
Также существует такой вид комментария:
Такой вариант удобен, когда нужно задокументировать одну строку внутри функции, или дать описание переменной или члену класса/метода. Обратите внимание, что между слэшем и стрелкой нет пробела.
Команды
В JavaDoc есть так называемые команды. Команды служат для детализации, выделения документации. Команд в JavaDoc довольно много, плюс можно вводить свои. Те команды, которые используем мы, я опишу далее. К сожалению, многие команды (почти все) в C++ не поддерживаются так, как хотелось бы (так, как это сделано в Java). Но тем не менее это отличный способ структурировать вашу документацию, обеспечить удобство при чтении и поддержку Doxygen. Я настоятельно рекомендую пользоваться командами.
Классы, структуры, перечисления, области видимости
Документация должна находиться строго до объявления/описания кода. Это позволит нашим IDE, и в дальнейшем Doxygenу, подхватить комментарии.
Мы документируем такой код многострочным комментарием, даже если описание влезает в одну строку.
Это позволяет комментариям не выбиваться из общего стиля документирования. Комментарии в одну строку блочного кода должны быть редкостью!
Для указания краткого описания может быть использована команда @brief. Указанный после команды текст, вплоть до конца параграфа, будет относиться к краткому описанию, и для отделения от основного используется пустая строка.
Также можно (и даже нужно) добавлять команду @example. Такой вариант позволит быстрее найти пример использования кода.
Это отличный вариант соблюдения 2 пункта из советов.
Документация функций/методов
Функции и методы также должны документироваться строго над объявлением/описанием. Здесь я также выступаю за многострочные комментарии по тем же причинам, что и выше.
int sum(int a, int b)
Опишите поведение функции/метода в случае ошибки (что возвращает, какие исключения кидает). Для этого можно использовать команду @throw.
Документация членов в классе/структуре, переменных в функции, значений в перечислениях
Для таких объектов будет удобен такой стиль документации:
Или на крайний случай
Документируйте переменные однострочными комментариями, старайтесь уместить комментарий в одну строку. Там, где это невозможно, используйте многострочные комментарии.
Более подробно о технических деталях документации рассказано тут.
Как обеспечить качественную документацию?
Доверить ревью новичку даст два больших плюса:
В перспективе вы получите:
Подробную и качественную документацию
Более быстрый рост и включение в проект своих новых сотрудников
Резюме
Понятно, что все, о чем я рассказал выше, «хорошо только на бумаге». Вероятней всего, на практике вы столкнетесь с трудностями: негодование ваших коллег/сотрудников о «бесполезной» работе, «бедной» документации, несогласия о стиле. Но не мне вам говорить, что такие изменения никогда не даются легко:) Грамотный подход к решению вопроса документации в перспективе окупит себя.
Ссылки, которые помогли мне к подготовке данного материала:
Автоматическое создание документации к программам на MQL5
1. Введение
Большинство Java программистов знакомы с автоматическим созданием документации, которая может быть создана при помощи программы JavaDocs. Идея заключается в структурированном комментировании кода и создании удобного файла справки.
В мире C++ также есть несколько автоматических генераторов документации, одними из лидеров являются программы Microsoft’s SandCastle и Doxygen.
2. Программа Doxygen
Программа Doxygen является системой автоматического создания документации c открытым исходным кодом в соответствии с GNU General Public License. Это означает, что ее разработка была похожа на другие проекты с открытым кодом, такие как Linux и Mozilla. Ее можно бесплатно скачать и использовать, исходный код Doxygen открыт для всех. Программа была разработана и совершенствуется несколькими разработчиками.
2.1 Загружаем Doxygen
Рис 1. Загрузка Doxygen
2.2 Настраиваем и запускаем Doxygen
Теперь все готово. Имейте в виду, что Doxgyen сохранит данные настройки в конфигурационном файле. Подготовленный файл с настройками приложен к статье.
Рис 7. Запуск Doxygen
2.3 Использование Doxygen
В качестве примера рассмотрим функцию CiMACD::Create() в файле MQL5/Include/Oscilators.mqh. Имейте ввиду, что файлы с описанием индикаторов отсутствуют в самой первой поставке MetaTrader 5. Для их получения, возможно, понадобится скачать последнюю версию MetaTrader 5.
Некоторые простые изменения ключевых слов позволят программе Doxygen правильно интрепретировать комментарии.
Для этого комментарии должны быть вида «///» (вместо «//»), в описании входных параметров «INPUT:» нужно заменить на «\param«, а «OUTPUT:» на «\return«.
После обработки программой Doxygen, файл справки будет выглядеть, как показано на рис. 8:
Рис 8. Описание функции CiMACD::Create(), созданное Doxygen
2.4 Используем Doxygen для документирования всего кода, поставляемого с MQL5
Я написал утилиту в виде скрипта MetaquotesCommentsToDoxygen.mq5 (прилагается к статье), который производит автоматическую конвертацию комментариев разработчиков компании MetaQuotes, таким образом, чтобы Doxygen смог их интерпретировать. Этот шаг не является необходимым для создания файла справки, однако он позволяет продемонстрировать полезные дополнительные возможности документирования, реализованные в программе Doxygen.
Для создания справки по всему коду MQL5, поставляемому с MetaTrader, нужно сделать следующее:
Если нужно включить в документацию обработку комментариев, их нужно предварительно структурировать:
Рис 9. Список классов, созданный Doxygen
Рис 10. Диаграмма потомков класса CArrayObj, созданная Doxygen
Рис. 11. Список функций класса CArrayObj, созданный Doxygen
Рис 12. Список определений (defines), созданные Doxygen
3. Программа Microsoft HTML Help Workshop
Остался всего один шаг для того, чтобы сделать еще более удобной документацию, созданную при помощи Doxygen. Программа Doxygen создает файл index.html, который содержит ссылки на множество других html-файлов и картинок. Это похоже на небольшой web-сайт, такая громоздкость делает документацию неудобной для распространения.
Давным-давно Microsoft осознала, что файлы справки для Windows-приложений лучше делать в HTML, для этой цели они разработали программу HTML Help Workshop. Эта программа берет файлы, созданные при помощи Doxygen, и компилирует их в один файл справки CHM. Файлы справки MetaTrader 5/MQL5 имеют тот же формат.
3.1 Загружаем HTML Help Workshop
Вы можете скачать и установить htmlhelp.exe с сайта Microsoft.
Рис 13. Загрузка HTML Help Workshop
3.2 Создаем скомпилированный файл справки HTML
Результаты работы Doxygen могут быть легко сконвертированы в файл справки CHM при помощи программы HTML Help Workshop. Используя наши настройки, Doxygen создает файл index.hhp, готовый для использования в программе HTML Help Workshop, как показано на рис. 14.
Рис 14. Местонахождение файлов index.htm и index.hhp, созданных Doxygen
Рис 15. Компиляция файлов в CHM при помощи HTML Help Workshop
. когда она завершена, можно скопировать и переменовать созданный файл index.chm в папку MetaTrader 5/Help, как показано ниже на рис. 16 и 17.
Рис 16. Местонахождение созданного файла справки index.chm
Рис 17. Копируем index.chm в каталог справки MQL и переименовываем его в MQL5 codeset help.chm
4. Итоги
Результаты данной работы убедили меня использовать Doxygen (или похожие программы) в будущем для создания документации к любому моему коду на MQL5, это значительно облегчает его понимание и использование. Надеюсь, что другие авторы также найдут Doxygen полезным.
Автоматическая генерация технической документации
Продолжая тему использования Asciidoc (и других аналогичных форматов) для организации процессов непрерывного документирования, хочу рассмотреть тему автоматический генерации технической документации.
Автоматическая генерация документации — распространенный, но очень расплывчатый термин. Я понимаю под этим термином извлечение для представления в удобном виде информации, содержащейся в исходном коде и настройках документируемой программы (информационной системы).
Общая схема автоматической генерации документации
Если рассматривать процесс автоматической генерации как чёрный ящик, то на входе имеем исходный код, а на выходе — документацию или её фрагмент. Однако в реальности при автоматической генерации документации целесообразны еще два промежуточных звена.
За исключением самых простых случаев, документация готовится в различных выходных форматах (html, docx, odt, pdf и т.п.) и собирается из разных источников (в том числе не автоматически генерируемых) поэтому целесообразно использовать специальные форматы для подготовки документации. Предположим, необходимо подготовить документацию по стандартам ЕСКД? Эта проблема, описана в предыдущей статье. При решении проблем автоматической генерации хватает проблем и без требований ГОСТ.
Общая схема генерации документации выглядит следующим образом:
Рассмотрим практические приёмы, которые можно использовать при реализации ИТ-проектов. Для примеров будем использовать Asciidoc, однако приёмы применимы к любым языкам разметки текста(reStructuredText, Markdown), и текстовым маркапам для построения диаграмм (рекомендую проект kroki, который позволяет быстро ознакомиться и внедрить наиболее популярные средства построения диаграмм).
Преобразование исходного кода в структурированный формат
Единых подходов к превращению исходного кода в структурированный формат не существует. Рассмотрим наиболее частые варианты.
Информация для документации извлекается из структуры исходного кода
Как правило, используются дополнительные средства языка, обычно комментарии в специальном формате (комментарии Javadoc, ReST и т.п.) и аннотации.
Средств, обеспечивающих преобразование исходного кода в документацию, причём очень зрелых, много. Можно смело брать и использовать подходящие для конкретного проекта. Разработка собственных средств затратна. Мы пошли указанным путём только раз, разрабатывая проект для миграции структуры базы данных. Целесообразность определялась использованием средства во всех наших проектах и желанием попробовать свои силы.
Следующие подходы более гибки с точки зрения настройки автоматической генерации документации в реализуемых проектах.
Структурированный формат получается как один из результатов исполнения исходного кода
При данном подходе считывается и сохраняется в структурированный формат состояния объектов (например, структуры базы данных, конфигурации развернутой среды информационной системы и т.п.), создаваемых в результате работы приложения.
Отдельно отметим использование для документирвоания логов. Типовой пример — тесты. Например, большинство инструментов для тестирования выдают результаты в формате Junit xml report. Это, позволяет сделать универсальные инструменты генерации отчётности по тестам, самый известный, наверное — Allure Framework.
В этой статье показано, как используют JSON-файлы, которые генерирует при работе Cucumber, как документация строится на основе логов, создаваемых в результате работы тестов.
Типовой пример создания документации на основе считывания состояния объектов, создаваемых в результате работы приложения, — документирование структуры БД. В конце раздела приведен пример, иллюстрирующий данный подход.
Исходный код сразу представляет собой структурированный формат
Многие языки уже реализованы в структурированном формате (например, xsd-схемы, OpenAPI, различные DSL для описания предметной области, файлы настроек).
Иногда проводят предварительную обработку этих форматов, например, объединение спецификации в единую иерархическую структуру (так называемая операция «flatten»).
Частным (и частым) случаем является ситуация, когда настройки содержатся в базе данных.
Пример — генерация документации по структуре базы данных
Пример иллюстрирует достаточно частую ситуацию, когда информация для документации хранится в таблицах СУБД.
Создаём скрипт, описывающий структуру БД. Этот скрипт не выглядит как исходник для поддержания структуры БД, однако, как это не парадоксально, таковым является, подробности в документации к уже упомянутому проекту. Это также может быть миграционный скрипт в любой системе контроля версии базы данных.
Применим скрипт к базе данных и воспользуемся двумя инструментами СУБД (пример приведён для PostgreSQL): динамическими представлениями для извлечения сведений о структуре и возможностью создавать JSON-файлы на основе результатов сохранения запросов.
В результате получим JSON-файл:
В следующем разделе будет показано, как этот файл превратить в документ.
Использование шаблонизаторов
Для превращения структурированного файла в документ используют специальный тип языков,
шаблонизаторы. Шаблонизатор позволяет задать правила обхода иерархической структуры данных и правила, по которым элементы иерархии исходного документа преобразуют в выходной документ.
Формат этих правил достаточно простой, они безопасны с точки зрения исполнения, поэтому часто шаблонизаторы используются для настройки различных аспектов работы приложений непосредственно пользователями.
Самым известным языком обработки шаблонов (но далеко не самым простым) является XSLT. Самым минималистичным — Mustache.
Свой язык написания шаблонов и шаблонизатор также создать довольно просто. Например, для создания системы генерации отчётов в форматах Excel и ods мы пошли этим путём.
Можно вообще обойтись без шаблонизатора, просто структурировать код определенным образом, в этой старой статье 2003 года Мартин Фаулер признается в нелюбви к XSLT и заодно объясняет, как его заменить кодом, написанным на языке Ruby. За 18 лет оказалось, что и статические языки также можно прекрасно использовать для этих целей, и XSLT прекрасно себя чувствует, и предложенный в статье подход оказался очень хорош.
В примерах будет использоваться Liquid для работы с JSON и XSLT для работы с XML. В обоих случаях будет использоваться реализация в Ruby, потому что (1) Наиболее распространенный в настоящий момент процессор Asciidoc — Asciidoctor — написан на Ruby (2) Ruby-скрипты отлично работают в java и javascript, что часто позволяет не плодить цирк технологий.
Пример генерации документа из JSON-файла
Рассмотрим простой пример по генерации документа на основе полученного выше JSON-файла.
Генерация диаграммы в формате PlantUML:
На выходе получаем следующий текст диаграммы:
Аналогично сгенерируем документ в формате Asciidoc:
Для объединения обоих кусков в один документ воспользуемся директивой include:
Синтаксис Asciidoc рассмотрен в статье Asciidoc для ЕСКД. Подробнее структурирование документации в Asciidoc планирую описать в отдельной статье. Здесь лишь хотелось бы отметить, что при вставке диаграммы мы указываем параметры её отображения. В разных документах одну и ту же диаграмму мы можем отобразить по-разному (в разных цветах, с разным разрешением, в разной ориентации и т.п.).
Результаты превращаем в файл в формате Microsoft Word с помощью проекта, о котором рассказано в предыдущей статье.
Ключевые техники, используемые при генерации документации
Для рассмотрения ключевых техник приведём пример с преобразованием XML-файла.
Для примера возьмем выписку из ЕГРЮЛ от Федеральной налоговой службы. Не совсем документация, но удобно для демонстрации основных приёмов преобразования структурированных данных в документацию.
Исходные данные (схема xsd и пример сообщения) взяты на сайте СМЭВ 3 — https://smev3.gosuslugi.ru/portal/inquirytype_one.jsp?id=41108&zone=fed. Для примера приведём небольшую часть выписки из ЕГРЮЛ:
Как видно, названия тэгов и атрибутов вполне говорящие, но мы возьмем полные названия параметров из схемы xsd.
Преобразование выписки из ЕГРЮЛ в формат Asciidoc выглядит следующим образом:
Наименования тэгов и атрибутов XML-документа обёрнуты в фигурные скобки — специальный синтаксис для отображения значений атрибутов Asciidoc. Значения атрибутов легко извлекаем из xsd-схемы с помощью следующего преобразования:
Объединим полученные значения атрибутов Asciidoc (два файла, т.к. описание сервиса по выдаче ЕГРЮЛ состоит из двух схем xsd) и файл с содержанием выписки:
На выходе Microsoft Word даёт следующую картинку:
Борьба с пробельными символами
Поскольку конечным форматом преобразования является текстовая разметка, вопрос пробелов крайне важен: текст, смещенный на несколько пробелов, может быть воспринят как блок с моноширинным текстом.
Пробелы могут влиять на эстетику, читаемость и обрабатываемость выходного документа. Например, после каждого абзаца в Asciidoc должно быть два переноса строки. Их может быть и три, но читается файл хуже. Во многих автоматически сгенерированных документах количество переносов строк абсолютно не предсказуемо. Особенно это неудобно при сравнении версий файла. При наличии на выходе файла в формате XML или JSON можно было бы применить утилиты, создающие красивый выходной файл. Для текстовых маркапов, насколько я знаю, таких утилит не существует.
С другой стороны, крайне важно, чтобы сам шаблон был красивым и удобным для чтения и редактирования, чтобы, как минимум, были отступы в циклах и условных операторах.
Поработав со многими шаблонизаторами, пришёл к выводу, что единственный практически универсальный вариант — указать шаблонизатору, чтобы он вырезал все пробелы и переносы, а переносы указывать вручную в шаблоне. В приведенном примере есть опция и после каждой выводимой строчки помещена команда
. Некоторые шаблонизаторы воспринимают \n как символ переноса. Если нет, необходимо провести пост-обработку выходного файла и самостоятельно заменять данную комбинацию на перенос строки.
Рекурсия
Рекурсия обеспечивает наглядный способ обхода узлов структурированного документа с большим количеством единообразных уровней иерархии, как в приведённой выписке из ЕГРЮЛ.
Экранирование и другие операции со вставляемыми данными
Данные для вставки в Asciidoc файл могут вступить в конфликт с разметкой Asciidoc. Например, вы хотите взять текст из Open API спецификации и добавить символ « ; ». Однако разработчик мог при описании сам поставить тот же символ. В результате в выходной файл попадёт два символа « ;; » и Asciidoc будет воспринимать текст как терминологический список, и хорошо ещё, если мы быстро поймём, почему на выходе текст отформатирован странно.
Для полного отключения синтаксиса Asciidoc во вставляемых значениях, достаточно их просто экранировать.
Выводы
И анонс: следующая статья будет посвящена вопросам обеспечения качества документации в формате Asciidoc.