Генерация проектной документации на основе моделей

Во время разработки моих проектов я обнаружил, что создаю несколько больших документов с небольшими изменениями только в нескольких параграфах. Например, один и тот же план конфигурации будет использоваться в разных проектах, но каждый документ должен соответствовать конкретным данным и соответствовать некоторым конкретным требованиям. Будучи ленивым человеком и фанатом модельно-ориентированной разработки, я искал способы оптимизировать этот процесс и получил следующие варианты:

  • Шаблоны документов - использование шаблонов основных документов (презентация) с формами (модель) или ограничение издания документа только несколькими ключевыми полями, а затем перекрестная ссылка на введенные данные по всему документу сделает свое дело... но я все еще чувствую, что могу немного больше расцепить оба слоя.
  • UML-моделирование. Используя инструменты CASE с поддержкой UML, я подумал, что смогу смоделировать свои документы как пакеты и классы с аннотациями, изменить модель для каждого проекта и сгенерировать отчет, используя шаблон документа. Проблема в том, что эти инструменты не предназначены для обработки больших кусков текста, и у меня есть некоторые трудности для прогресса.
  • Моделирование процессов - Использование Eclipse EPF https://www.eclipse.org/epf/ кажется немного излишним для того, чего я хочу достичь. Помните: я ленивый человек.

Я хотел бы спросить сообщество об их опыте работы с документацией на основе моделей или об их способах оптимизации создания документов на протяжении всего цикла разработки программного обеспечения.

1 ответ

Решение

Я не уверен, что полностью понимаю, поэтому извиняюсь, если это не соответствует цели.

Я столкнулся (я думаю) с подобной проблемой, когда существует множество взаимосвязей между контентом и документами, в которых он должен быть представлен. Например, "обзор проекта", который необходимо включить в документ с требованиями, проект план и т. д.

На данный момент лучшее решение, которое я нашел, это:

  1. Напишите каждый раздел в формате Markdown. Есть несколько хороших редакторов, которые делают написание Markdown простым и эффективным (например, Mou на OSX).
  2. Используйте Pandoc для преобразования Markdown в реструктурированный текст (RST).
  3. Используйте Sphinx для генерации документов из файлов RST.

У меня есть несколько шаблонов документов Sphinx, каждый из которых объединяет некоторые общие разделы с другими, специфичными для этого документа. Если один из общих разделов будет обновлен, легко будет заново сгенерировать все документы для включения. Контроль версий довольно прост, так как все исходные файлы представляют собой простой текст. Sphinx также может легко создавать несколько форматов: например, html для размещения в сети или pdf для печати / распространения.

Вы можете устранить необходимость в шаге 2, написав на родном языке RST. Для меня дополнительный шаг того стоит, так как я не нашел RST-редактор, который был бы таким же удобным и эффективным, как Mou. YMMV конечно.

Это не идеальное решение: например, создать ссылки между разделами не так просто. Но в целом это хорошо работает для моих нужд.

НТН.

Другие вопросы по тегам