Экспорт спецификаций на основе шаблона Microsoft Word (ноябрьское обновление)

Используя преимущества Python и Rest API портала Requirements & Systems Portal, которые обеспечивают полный доступ ко всем данным, и сочетая их с функцией Merge Fields в Microsoft Word, вы можете одним щелчком мыши экспортировать спецификации в документ Word. Эта функциональность дает вам возможность выбрать, какие поля требований вы хотите включить в документ и как их разместить.

Поля слияния и шаблоны

Поля слияния используются в качестве ссылки на поле данных по его названию. Когда шаблон документа объединяется со значениями из источника данных, информация из поля данных заменяет поле слияния.

Создавая шаблонный документ с различными полями слияния, можно быстро генерировать на их основе выходные документы одного типа (спецификации или другие).

Создание нового поля слияния

1. Откройте редактируемый документ и перейдите на вкладку Insert вкладку.

2. Откройте Quick Partd меню и выберите Field. Откроется диалоговое окно Field откроется диалоговое окно.

3. В диалоговом меню поля выберите Merge Field из списка слева. Введите имя поля слияния в Field name текстовом поле справа и нажмите кнопку OK.
   Подсказка: чтобы было легче отслеживать, назовите поле по данным, которыми оно будет заменено

4. Поле слияния будет вставлено в файл Word. Объект должен быть выделен серым цветом, если вы нажмете на него.

К объединяемым полям, для которых уже определены соответствующие функции Python, относятся:

"req_id" - Идентификатор требования
"req_title" - Титл требования
"req_text" - Текст требования
"req_state" - Состояние требования 
"req_type" - Тип требования
"req_rationale" - Обоснование, связанное с требованием 
"images" - Изображения, прикрепленные к Требованию
"specification_name" - Спецификация, содержащая Требование
"имя_раздела" - Раздел, содержащий требование
"req_compliance" - Заявление(я) о соответствии требованиям
"req_comp_comment" - Комментарии к соответствию требованиям
"req_owner" - Владелец требований 
"req_applicability" - Применимость требований
"req_ver_methods" - Методы проверки требований
"req_ver_m_text" - Комментарии к методам проверки требований
"req_ver_closeout_ref" - Ссылки на закрытие методов верификации требований
"req_ver_status" - Статус методов верификации требований

Создание шаблонов (для репликации шаблонов)

Комбинация полей слияния может быть использована для создания файлов шаблонов, которые будут использоваться для генерации документов спецификации.

Ниже показан пример шаблона, в котором одни поля записаны "обычным текстом", а другие - как часть таблицы. Этот пример является базовым для сценариев Python, которые будут описаны в следующем разделе.

Результирующий вывод этого шаблона будет выглядеть так, как показано на рисунке ниже

Сценарий Python для заполнения шаблона

Сценарий Python, который используется для создания документов на основе шаблона, заполненного полями слияния, использует следующие основные пакеты:

• valispace - API python портала Requirements & Systems Portal позволяет получать доступ и обновлять объекты в Requirements & Systems Portal.

• docx-mailmerge2 - Выполняет Mail Merge (заменяет поля слияния нужными данными) для файлов Office Open XML (Docx) и может использоваться на любой системе без необходимости установки Microsoft Office Word.

• python-docx - Библиотека Python для создания и обновления файлов Microsoft Word (.docx).

• htmldocx - Библиотека Python для преобразования HTML в Docx. Используется для сохранения формата из Requirements & Systems Portal в Word (жирный, курсив, пулевые точки...)

Код разбит на 3 типа функций:

• Master functions - Состоит из main и create_specification_documentкоторые содержат логику экспорта требований в конечный документ путем заполнения заданного шаблона

• Requirement data extract functions- Все функции для извлечения данных о требованиях, таких как тип требования, состояние, изображения..

• Document "Format" functions- Функции, выполняющие форматирование, например, удаление пробелов, обеспечение того, чтобы таблицы не разбивались на части в итоговом документе

В следующем подразделе мы кратко расскажем об этих функциях.

Основные функции - Главная

Эта функция позволяет пользователю ввести имя домена, его имя пользователя и пароль, идентификатор проекта, на основе которого генерируются спецификации, и путь к файлу шаблона

Затем эта информация будет использована для:

1. Войти на портал требований и систем с помощью Python API;

2. Загрузить общие данные проекта, такие как спецификации, изображения, типы требований и другие;

3. Вызовите функцию create_specification_documentдля каждой спецификации в выбранном проекте.

Мастер-функции - Создать_спецификацию_документа

Эта функция создаст файл спецификации, заполнив поля слияния в шаблоне соответствующими данными о требованиях.

Первоначально необходимо собрать все требования для выбранной спецификации:

all_specification_requirements = get_map(api, f "requirements/complete/?project="+str(DEFAULT_VALUES["project"])+"&clean_html=text&clean_text=comment", "id", None, filter_specification)
    if len(all_specification_requirements) 1:
        print("Нет требований для спецификации -> "+ specification_data['name'])
        return

Затем он упорядочит данные о требованиях по разделам, начиная с требований без разделов.

Чтобы получить эти требования, не относящиеся к разделу, вспомогательная функция get_requirements_without_sectionиспользуется для фильтрации всех требований к спецификации, которые не имеют группы (как секции хранятся в бэкенде Requirements & Systems Portal), и сортировки в алфавитном порядке.

    #Сначала мы добавим в документ требования без раздела
    no_section_requirements = get_requirements_without_section(all_specification_requirements)

Теперь, когда все требования без разделов собраны, пришло время подготовить данные, которые будут заполнять поля слияния. Эти данные извлекаются с помощью функции Requirement data extract functions и будут сохранены в списке python, как показано в коде ниже.

template_data.append({
                "specification_name" : CURRENT_SPECIFICATION["name"] if counter == 1 else "",
                "section_name" : "", 
                "req_id" : reqdata['identifier'],
                "req_title" : reqdata['title'],
                "req_text" : reqdata['identifier']+"_docx",
                "req_type" : req_type,
                "req_rationale" : reqdata['comment'],
                "req_ver_methods" : req_vms,
                "req_applicability" : req_applicability, 
                "images" : "Images_Placeholder_"+str(requirement) if requirement_with_images == True else "No_Images"
            })

Для большинства полей Merged данные отображаются напрямую, но для imagesиreq_textданные будут объединены на более позднем этапе:

• Для images флаг, указывающий, есть ли у требования изображения или нет, хранится как данные

• Для req_textв качестве данных сохраняется заполнитель. Этот плейсхолдер также будет использоваться в качестве ключа в списке, который содержит результат разбора текста требования из HTML в Word, как показано в следующем коде

  docx_list[reqdata['identifier']+"_docx"] = new_parser.parse_html_string(reqdata['text'])

Тот же процесс будет повторен для требований, имеющих секции, и после этого данные будут объединены в поля шаблона и сохранены в новом файле:

document.merge_templates(template_data, separator='continuous_section')
document.write(OUTPUT_FILE)

Наконец, мы воспользуемся функцией Document "Format" functions для доработки документа, удалив пустые разделы и пустые заголовки, сохранив таблицы на одной странице, вставив в документ отформатированный текст требований и их изображения

    document2 = Document(OUTPUT_FILE)
    remove_all_but_last_section(document2)
    remove_all_empty_headings(document2)
    put_html_text(document2, docx_list)
    put_images(document2, all_project_images)   
    keep_tables_on_one_page(document2)

    document2.save(OUTPUT_FILE)
    print("Создан документ спецификации -> "+ specification_data['name'])

Функции извлечения данных из требований

Для извлечения данных из требований существуют следующие функции:

• get_requirements_without_section - Возвращает отсортированный список всех требований без раздела

• get_specification_sections - Возвращает список всех разделов данной спецификации

• get_section_requirements - Возвращает отсортированный список всех требований данного раздела

• get_requirement_images - Возвращает массив всех изображений требований

• get_requirement_type - Возвращает название типа требования

• get_requirement_state - Возвращает название требования Состояние

• get_requirement_owner - Возвращает группы пользователей и имя и фамилию владельца требования

• get_requirement_applicability - Возвращает список всех применимых к требованию типов блоков, разделенных знаком ";"

• get_requirement_verification_methods - Возвращает название всех методов верификации требования, разделенных символом ";"

• get_requirement_verification_methods_newline - Возвращает название всех методов верификации требований, разделенных новой строкой

• get_requirement_verification_methods_comments - Возвращает все комментарии к методам проверки требований, разделенные двойной новой строкой

• get_requirement_verification_status - Возвращает статус всех методов проверки требований, разделенный символом ";"

• get_requirement_verification_closeout_refs - Возвращает названия ссылок на закрытие для каждого метода верификации требований, разделенные символом ";"

• get_requirement_attachments_references - Возвращает название всех вложений требований, разделенных символом ";"

• get_requirement_custom_field - Возвращает значение определенного пользовательского поля требования, переданного в качестве аргумента функции

Функции "Форматирования" документа

Для форматирования конечного документа используются следующие функции:

• keep_tables_on_one_page - Форматирует итоговый документ так, что таблицы не могут иметь содержимое ячеек на разных страницах.

• remove_all_empty_headings - Форматирует итоговый документ, удаляя все пустые заголовки

• remove_all_but_last_section - Форматирует итоговый документ так, чтобы в нем был только один раздел вместо нескольких

• put_images - Заменяет плагин изображений на изображения каждого требования

• clone_run_props - вспомогательная функция для копирования свойств одной проги в другую (используется для копирования свойств HTML-форматированного текста)

• put_html_text - Заменяет заполнитель текста требования соответствующим форматированным текстом, таким как полужирный, курсив, подчеркивание, зачеркивание и пулевые точки

Загрузите последнюю версию шаблона Generic, сценария Python или исполняемого файла

Generic Specification Creation Nov2023.py Generic Specification Template.docx требования.txt

Что нужно отредактировать перед запуском скрипта:

Полная процедура запуска этого кода, начиная с создания скриптов и заканчивая генерацией документа, показана в этом видео ниже (без звука).

Line 27 - Line 30 Пользователю необходимо определить имя пользователя и пароль для запуска скрипта. Пользователь может использовать секретное управление и запустить сценарий или напрямую ввести имя пользователя и пароль в сценарий. Однако пароль будет виден всем пользователям в развертывании. Поэтому мы рекомендуем вам использовать "Управление секретами".

Line 31 Скопируйте название спецификации и введите в эту строку.

Line 32 Загрузите шаблон общей спецификации в управление файлами, скопируйте его "ID" и добавьте его в эту строку.

Line 33 Добавьте "ID" проекта, в котором находится спецификация.

Line 34 Вы можете задать имя экспортируемому документу.

Если вам нужны рекомендации по изменению шаблона, извлечению другой информации для наполнения шаблонов или любые вопросы, связанные с этой функцией, пожалуйста, не стесняйтесь отправлять нам свои вопросы/запросы через нашу страницу поддержки Altium.