Генерация документов. Легко и свободно
Продолжая тему генерации документов на основе шаблонов, я хочу обсудить создание документа, в котором кроме относительно постоянных частей есть части, вид и содержание которых целиком зависят от данных. Т.е. речь не идет о тривиальном заполнении полей или простых таблиц. Речь идет о таблицах с разнообразной фактурой, с различным количеством колонок под одной шапкой и сам вид таблицы определяется данными.
Для реализации такого документа в шаблоне можно заранее определить отдельные возможные строки таблицы, дать им имя, а затем из этих строк собирать таблицу так же, как бусинки насаживаются на нить, как нити укладываются слой за слоем в ткань с требуемым узором.
В процессе генерации эти вспомагательные строки удаляются из документа. Какая именно строка должна быть вставлена в документ определяется по ее имени. Именованная строка не обязательно должна быть строкой таблицы, это может быть текст с нужными атрибутами отображения.
Таким образом можно собрать документ, где текст чередуется с разнообразными таблицами. В шаблоне задается помимо именованных строк место, откуда начинается построчная печать. Задача программиста в данном случае сводится к формированию XML, в котором помимо данных будет указано, какой строкой их отображать. Т.о. достигается почти полное (только имя строки задает формат) разделение данных от их представления. И что приятно, имена строк могут быть осмысленными, а генерация происходит быстро.
В заключение хочу добавить, что мест в шаблоне, куда надо впечатывать строки с данными, может быть несколько. Каждое место имеет свое имя (идентификатор). В XML с входными данными необходимо передавать в определенном тэге это имя перед тем как печатать строка за строкой данные. Естественно, данные для печати должны быть отсортированы в порядке следования строк.
Генерация документов в doc, excel, pdf и других форматах на сервере
Выгрузка отчетов в различных форматах — типовая задача для многих проектов. И сейчас есть немало инструментов для этого. Среди них есть интересный вариант, который применяется, как мне кажется, не часто, но он однозначно стоит внимания. Потому что позволяет получить документ в нужном формате буквально одной командой. О нем и расскажу.
Я буду не многословен и сразу скажу, что речь идет о конвертере, встроенном в пакет LibreOffice. Вы можете запустить конвертацию из консоли, чтобы увидеть как это работает:
Эта команда конвертирует файл html.html в pdf файл. Количество поддерживаемых форматов впечатляет.
Выгода от использования такого инструмента очевидна. Вместо того, чтобы писать код для генерации документов в каждом из нужных форматов, просто создаем обычное html-представление. Далее сгенерированную страницу прогоняем через конвертер.
Запуск конвертации из PHP
Для установки конвертера на сервере придется установить пакет libreoffice-core:
Чтобы было удобно работать с утилитой из PHP, я написал обертку.
Обертка позволяет вам не думать о работе с временными файлами, подставляет в команду некоторые параметры по умолчанию, содержит константы с описанием доступных форматов, а также дает возможность задать таймаут на выполнение конвертации.
Для работы с оберткой подключаем ее к своему проекту через composer:
Использовать ее можно так:
В результате будет сформирован docx файл. Больше примеров можно найти на гитхабе.
Разумеется, в качестве бонуса можно запускать конвертацию в другую сторону — из doc в html и отображать содержимое офисных документов в браузере. Качество конвертации будет не всегда на высоте, но для каких-то случаев вполне подойдет.
Несколько граблей
Будет полезно рассказать про несколько особенностей, с которыми я столкнулся при работе с этой утилитой.
1. Применение CSS стилей. При преобразовании html в нужный формат имейте ввиду, что такая запись воспринимается корректно:
А такие записи будут обработаны точно так же, как если бы class мы совсем не указали:
2. При преобразовании html в нужный формат не всегда срабатывают описания стилей и иногда приходится экспериментировать, чтобы заработало. Например, так не работает:
3. Одно и то же преобразование можно выполнять с помощью разных конвертеров. При этом результат будет существенно отличаться. Если у вас на выходе получится не очень красивый документ, попробуйте принудительно задать используемый модуль, например:
4. Можно ли настроить ширину строк в таблице — для меня пока загадка. И в целом со стилизацией таблицы при преобразовании html в docx или pdf у меня возникли затруднения. Поэтому на мой взгляд подход трудно будет применять для генерации сложных печатных форм, таких как счет-фактура.
Генерация документов — личный опыт
В своих предыдущих статьях я пытался показать отдельные фрагменты Генератора документов. Как стало понятно из обсуждений, отдельные его фрагменты существуют в различных реализациях и обсуждать их не интересно. Действительно, зачем обсуждать отдельные строительные кирпичики, когда не видишь здания целиком. Поэтому в этой статье я попытаюсь показать здание целиком, чтобы не обсуждать его отдельные кирпичики. Я попытаюсь описать свое видение реализации генератора документов, опираясь на личный опыт, полученный в одном из крупнейших банков России. Я шел от практики, реализовал генератор в MS Word и Excel, вот что в результате этого процесса нарисовалось.
1. Генератор должен уметь на основе шаблонов генерировать документы. Полученные документы должны быть максимально готовыми к использованию, они должны содержать минимальное количество мест, требующих после генерации ручной правки. Шаблоны должны разрабатываться и сопровождаться самим бизнесом, участие IT должно заключаться в обеспечении возможности получения из баз данных информации, требуемой для заполнения шаблонов. В дальнейшем станет ясно, что речь идет о значениях полей и ответов на вопросы.
2. Генератор должен на основе шаблонов автоматически строить UI формы для обеспечения ручного ввода информации, отсутствующей в БД. Таким образом, введя вручную значение такого поля, оно будет подставлено в разные места документа(тов), правильно сопряжено с другими словами, иметь правильный падеж и т.д. Значения, введенные вручную, должны сохраняться в БД и в случае необходимости копироваться в основную БД, обеспечивая принцип одного ввода. Часть полей должна быть просто показана на форме без возможности редактирования, только для визуального контроля.
Часть полей должна быть скрыта: — это вычисляемые поля и поля, которые на определенной стадии подготовки документа\договора заполняются прочерками. Значения полей с прочерками определяются позднее в процессе согласования условий, например, договора. Поля располагаются на UI форме в определенном порядке на определенных закладках и имеют соответствующий тип элемента (control) и маску для ввода. При выдаче команды на Генерацию значения полей верифицируются и в случае обнаружение несоответствий пользователь получает сообщение об ошибке или предупреждение.
Разработчики шаблонов с помощью специальной среды разработки устанавливают порядок следования полей, их расположение на закладках UI формы, выбирают форматы ввода\вывода, отмечают поля для заполнения прочерками и т.п. Роль IT в этих процессах может быть только консультационная. Практика показывает, что хорошая документация плюс наличие обучающих примеров, плюс уже обученный сотрудник, плюс дружественная среда разработки позволяют почти полностью освободить IT от подготовки шаблонов, форм ввода информации и вопросников. А это значит, что бизнес сам себя обеспечивает нужными документами, освобождает IT от рутины, устраняет посредников между требованиями и реализацией и работает практически во временном режиме, удобном самому бизнесу. Ну и, конечно, бизнес перестает платить за реализацию генерации документов сторонним разработчикам и некомпетентным исполнителям, которые не находятся в контексте бизнеса конкретной организации и ее практики.
Разработка шаблонов помимо понимания требований к конечному документу, это кропотливый труд, требующий внимания и прилежания. Разметка шаблонов будущего документа, это работа не для молодых, амбициозных, но нетерпеливых IT-шников, здесь нужны женские руки, женское прилежание и склонность лучше мужчин справляться с монотонными операциями подходит как нельзя кстати. Поддержка шаблонов, их модификация — это все же больше женский хлеб, чем мужской.
Я сам как-то попробовал разметить документ для бизнеса, и скажу честно, это не принесло мне радости, хотя дало несколько прекрасных идей для улучшения процессов подготовки шаблонов. С тех пор я сильно зауважал тех женщин, которые, не имея этих замечательных новшеств, терпеливо и без жалоб тянули свою нелегкую женскую долю.
3. Количество шаблонов должно стремиться к минимуму, но в то же самое время сами шаблоны не должны быть огромными. Сколько должно быть шаблонов и каковы их размеры должны решать сами разработчики шаблонов, т.е. бизнес. И точных правил, однозначно определяющих размеры шаблонов, не существует. Но рекомендации могут быть. Одна из них — чем больше по размеру шаблон, тем больше вычислительных ресурсов потребуется Генератору для генерации документов на его основе. Поэтому не стоит в один шаблон упаковывать весь мир.
Практически, размеры шаблонов определяются тем, сколько разнообразных документов можно сгенерировать из одного шаблона и насколько они будут похожи друг на друга, относятся ли к одной теме и т.п. Совершенно не редки шаблоны размером 100 и более страниц.
Когда я увидел впервые такие огромные шаблоны, я, при всем доверии к компетенции бизнеса, засомневался в правильности их выбора. Но чтобы указать бизнесу на его ошибки, нужно разобраться с тем, что неправильно было сделано и предложить лучший вариант, а это требует погружения в практику бизнеса, что, в свою очередь, потребует от IT-шника компетенций, не относящихся к его текущим умениям и навыкам. А посему, со своим уставом не надо ходить в чужой монастырь. Надо доверять людям, 100 страниц, значит 100.
Понятно, что разработчики шаблонов не оперируют понятиями производительности и не считают затрат вычислительных русурсов. Их интересует результат. Тем не менее они заинтересованы в том, чтобы генерация документов осуществлялась максимально быстро.
Поэтому разметка шаблонов должна позволять разработчикам шаблонов управлять скоростью генерации, и разработчики шаблонов, безусловно, такими возможностями пользуются. Идея сокращения размера шаблона заключается в том, что шаблон может быть большим, но состоять из кусочков, котрые подгружаются в память по мере надобности. Т.е. в процессе компиляции шаблона он по указаним в разметке разбивается компилятором на кусочки, которые в момент генерации документа будут подгружены в память в зависимости от того, какой документ из этих кусочков собирается. Т.е. с точки зрения разработчика шаблона, шаблон может быть большим, но с точки зрения Генератора, шаблон — это маленькая базовая часть плюс конкретные кусочки, подставляемые на свое изначальное место в случае надобности. Такой способ работы с шаблонами приводит к сокращению времени генерации и, соответственно, сокращению потребляемых вычислительных ресурсов. Ответственность за скорость генерации лежит при таком подходе на разработчике шаблона (а он работник бизнеса).
4. Генератор должен уметь включать в себя статьи, параграфы, части других документов, отсутствующие изначально в шаблоне. В шаблоне только отмечается место, куда такая информация может быть вставлена. Т.е. генератор должен уметь синтезировать документ из отдельных параграфов и фрагментов других документов. Здесь основная сложность заключается в сопряжении разнородного внешнего текстового материала с основным документом. Например, в библиотеке могут храниться отдельные пункты договора и, в зависимости от условий договора, эти пункты должны вставляться в основной документ. При вставке надо выровнять шрифт и отступы, определить номера пунктов договора, вычислить ссылки на другие пункты как текущего документа, так и на пункты другого документа (например, генерального договора) и т.п.
Все это требует с одной стороны определенной стандартизации ведения отдельных библиотечных пунктов, а с другой стороны, создателю шаблонов необходимо иметь под рукой набор элементов разметки, которые позволяют осуществить тонкую ручную настройку нестандартных фрагментов текста (мало ли из каких источников могут поступать документы (тексты, таблицы, графики, которые надо вставить в генерируемый документ). Библиотеку пунктов ведет и поддерживает бизнес. Изменение текста пункта приводит к изменению текста всех документов, которые включают в себя данный пункт. В процессе практики выясняется, какие части одного шаблона всегда совпадают с частями другого. В таких случаях эти части можно вынести из шаблона в библиотеку (или файловую папку, где лежат общие части для различных документов) и в случае изменений (а они не редки сегодня) редактировать не один и тот же текст в различных шаблонах, а править его в одном месте. Для быстрого нахождения нужного фрагмента он должен быть снабжен поисковым образом.
5. Атрибуты отображения текста в готовом документе должны быть достаточными, чтобы соответствовать потребностям бизнеса. Это толщина, наклон, подчеркивание и вычеркивание текста, его подсвечивание (highlight) определенным набором цветов (каждый цвет подсветки может нести смысловую нагрузку). Очень важна поддержка возможности отображения исправлений, когда в документе можно видеть первоначальный и исправленный вариант текста. Пользователь документа должен иметь возможность переключаться из режима отображения конечного вида документа в режим отображения правок (MS Word). Генератор должен уметь автоматически создавать оглавление документа, а также создавать сноски.
Также у разработчика шаблонов должен быть в ассортименте достаточный набор спецсимволов, которые однозначно интерпретируются пользователем документа, как то: всякого рода галки, квадратики с галками и без, указательный палец и др. Генератор должен уметь вставлять картинки из других документов или из файлов (например, QR-код), создавать ссылки на сайты, уметь впечатывать отдельные символы слова (например, кодовое слово) в ячейки обычно однострочной таблицы. И, конечно, должен быть доступен набор тэгов разметки, позволяющий создавать таблицы любой сложности, с разнообразием заголовков и строк таблицы. В дополнение к таким тэгам придаются тэги разметки, позволяющие удалять (сжимать) пустые строки или столбцы таблицы, если после генерации они не были заполнены данными.
6. Генератор должен уметь возвращать результат в вызывающую программу или сохранять готвый документ в файловую папку. Генератор реализуется в виде нескольких методов WEB-service, одним из которых является генерация документа или пачки документов по шаблону. Вызывать WEB-Service можно из любой программы или СУБД. Если результат сохраняется в файл, то очень важно иметь гибкую, настраиваемую по требованиям бизнеса, подсистему, которая определяет спецификацию самой папки и имя файла документа, которые могут быть интеллектуальными и включать в себя дату, имя клиента и т.п. Обычная практика работы с документами клиента приводит к созданию папки, где лежат все документы, относящиеся к сделке, в том числе не подготовленные генератором, и пользователям удобно использовать файловую «деревянную» структуру для работы с документами.
При генерации пачки документов по одному шаблону, если генерируемые документы кроме значения полей ничем не отличаются, можно значительно скратить время генерации, т.к. все подготовительные операции с шаблоном выполняются вначале только один раз, а затем по этой промежуточной форме шаблона производится генерация пачки документов. Например, набор документов по поручительствам может иметь одни и те же условия соглашения для поручителей, поэтому все документы должны отличаться только данными самих поручителей, их ФИО, адреса, должности и прочее. В этом случае выгодно использовать генерацию пачки документов по одному шаблону, и получить выигрыш во времени генерации за счет того, что генератор использует механизм использования промежуточной формы шаблона. Такая функциональность также должна поддерживаться генератором.
7. Представим себе документ, например, анкету, в котором есть раздел, включающий сведения о родителях. А у клиента нет родителей, и никогда не было. В одном месте анкеты он поставит галку, что родителей у него нет, а в другом месте сведения о родителях останутся незаполненными. После распечатки такой анкеты будет использована лишняя бумага. Действительно, если у клиента родителей нет, то и сведений о родителях в документе быть не должно. И таких моментов, вызывающих когнитивный диссонанс, в документах зачастую пруд пруди. Напрасно тратится энергия и труд, затраченные на производство бумаги, напрасно тратится время жизни человека, который просматривает такую анкету с пустыми полями. Этого быть не должно. Это могло быть раньше, в докомпьютерную эпоху, но сейчас, при наличии генератора документов такое расточительство должно быть прекращено. И все что нужно сделать IT-шникам, это всего-навсего получить заранее ответ на вопрос, есть ли у клиента родители, и в зависимости от ответа, запрашивать данные о них или исключить полностью из документа раздел сведений о них. Т.е. перед собственно заполнением полей документа должен быть пройден вопросник, ответы на вопросы которого являются аргументами как для функции получения списка полей, необходимых для заполнения в документе, так и аргументами функции генерации документа по конкретному шаблону.
Ответы на вопросы «высекают» из полиморфного шаблона только те части, которые соответствуют ответам, точно так же, как Микельанжело высекал из мрамора свои прекрасные творения. Составление вопросника — это отдельная тема, которую подробно в данной статье рассматривать я не буду, чтобы не «зашумлять» изложение темы о генераторе документов. Скажу только, что по разметке шаблона автоматически можно получить вопросник к нему, в случае, если тэги разметки однозначно определяют ответ на вопрос, а значит и сам вопрос. Т.е. если тэг ответа на вопрос (это уникальный код ответа) принадлежит только одному вопросу, то составление вопросника происходит автоматически, а порядок следования вопросов можно позаимствовать из уже существующих вопросников, что также не является сложной операцией. Вопросы и ответы к ним могут быть как обычные, составленные в дизайн тайме, так и динамические, получаемые из данных в СУБД. Вопросы могут иметь только один ответ или быть многозначными. Ответы на вопросы могут влиять не только на состав полей, появляющихся в UI форме для заполнения, не только на окончательную форму документа, но и на последующие вопросы. Например, если у вас были родители, то можно задать вопрос, вляются они резидентами или нет. Но если их не было и вы из туманности Андромеды, то вопрос про резиденство бессмыслен. Итак, по крайней мере двумя понятиями сотрудник, занимающийся разметкой, должен овладеть, это расставить в шаблоне поля и тэги ответов на вопросы. Т.к. обычные люди в голове спокойно удерживают 5-6 понятий на одну тему, то задача разметки пока что не видится мне слишком сложной. Овладевший двумя основными понятиями разметки сотрудник может сделать примерно то же, что программист, написавший на новом для себя языке программирования программу «Hello world». Этого, конечно, недостаточно, но это уже кое-что.
8. Не будем лукавить. «Зачем так много слов, так много треска». Работник бэкофиса, если он не слишком ленив, может обеспечить себя шаблонами сам. И зачем ему генератор, когда у него есть его собственные шаблоны на все типовые случаи жизни. Если что-то меняется в жизни, он создаст себе новый шаблон и с помощью команды Replace может быстро сделать нужный документ, например, типовой договор. Но вот ситуация, которая при таком подходе не работает. Т.е. она работает, конечно, но кое-как. Допустим, составлен первичный вариант договора поручительства и передан клиенту, а затем юристам на согласование. В результате правок через некоторое время на основе этого первичного документа появляется новый документ, в котором многие пункты первоначального варианта исправлены, дополнены и все такое. Теперь на основе этого нового варианта поручительства надо составить 10 или больше документов поручительств, где должны быть подставлены ФИО, адреса, должности и прочие реквизиты поручителей, а остальное содержимое документа должно быть таким, как в новом варианте поручительства.
Здесь возникает ситуация, когда у работника бэкофиса шаблона нет, т.к. на все случаи жизни шаблонами не запасешься и все варианты поручительств не переберешь. Вот случай, когда генератор действительно может проявить свое преимущество по сравнению с обычным ручным способом подготовки документов. Для этого генератор должен сгенерировать такой первичный договор поручительства, который после внесения правок клиентом и юристами может сам выступить в роли шаблона. Тогда подготовка 10 или более документов поручительств для разных поручителей займет несколько секунд работы компьютера, не будет содержать ошибок, опечаток и всего того, что может сделать любой человек в любой момент. Т.е. не только экономится время подготовки документов, но повышается их качество, т.к. компьютер не ошибается. Чтобы получить такую функциональность генератор должен в момент генерации первичного документа создавать налету скрытую разметку, которая существует в виде закладок и не видна людям, работающим с текстом документа. Каждая закладка однозначно соотнесена с именем поля, а значит, что в место документа, отмеченное закладкой, можно подставлять любые значения, но только способ подстановки будет отличаться от первичного. К сожалению, если говорить про MS Word, не всегда закладки сохраняются в документе после внесения правок, это зависит от способа, каким вместо одного текста был внесен другой. Чтобы устранить последствия исчезновения закладок, приходится делать дополнительные закладки, по которым можно вычислить место исчезнувших закладок. Такой механизм вполне работоспособен, жаль, что Microsoft ничего не предпринимает для стандартного решения этой проблемы. Ну может быть, когда-нибудь, когда что-то сдуется или изменится климат, данная проблема будет решена.
9. Шаблоны, содержашие в себе скрытую разметку, по сравнению с первоначальными шаблонами, являются ригидными. Но степенью ригидности, к счастью, можно управлять. Из ригидного шаблона можно получить гибридный (вот так рождаются каламбуры), для этого в части ригидного шаблона нужно подставить части из первоначального шаблона. Обычно в документе есть такие места (гипервариабельные), которые позволяют вернуть на место ту разметку, которая была в первоначальном шаблоне до генерации документа. Естественно, такие места надо разметить в шаблоне. В результате, даже после правок клиентом и юристами, шаблон, содержащий только закладки, остается достаточно гибким. К тем частям, которые вернулись из первоначального (или любого другого) шаблона, налету можно получить вопросник, если разметка с ответами на вопросы будет обнаружена в вернувшихся частях шаблона. Гибридный шаблон обеспечивает ту степень гибкости, которая во многих случаях оказывается соответствующей требованиям бизнеса.
Итак, я рассмотрел некоторые отдельные «кирпичики», которые нужно иметь, чтобы построить «здание» под названием «Генератор документов». Я старался акцентировать ваше внимание на том, чтобы шаблоны создавались самим бизнесом и участие IT было минимальным. Надеюсь, разговор о гибридных шаблонах тоже мог быть полезным.
Понятно, что во многих случаях достаточно иметь более простую машинку для подготовки документов. В тех организациях, где нет вопросов про родителей и документы однообразны и статичны, можно использовать рогатку вместо пушки. В тех же организациях, где имеется индивидуальный подход к клиентам и процесс подготовки договоров не автоматизирован
в достаточной степени, данная статья поможет определиться с требованиями к разработчикам того программного продукта, который сегодня по функционалу должен и может соответствовать описанию, данному мной в этой статье.
Автоматическая генерация технической документации
Продолжая тему использования 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.
