Конфигурирование состава документации на сайте#

Конфигурация сайта хранится в репозитории content-configuration и имеет следующую структуру:

site-config/
  product-registry/
    categories.json
    products.json
    components.json
  <PRODUCT-CODE-1>/ # Вариант с отдельным файлом для каждой версии продукта
    <VERSION-11>
      components.ini
    <VERSION-12>
      components.ini
    ...
    <VERSION-1N>
      components.ini
  <PRODUCT-CODE-N>/ # Вариант с единым файлом для всех версий продукта
    components.ini
  ...
  doc-config.ini

Пример структуры каталогов в репозитории конфигурации сайта:

content-configuration/
├── BD/                        // каталог с названием кода продукта
│   ├── 5.11.2/                // каталог с названием версии продукта
│   │   └── components.ini     // файл конфигурации продукта
│   ├── 5.15.0/
│   │   └── components.ini
│   └── ...
├── SEI/
│   ├── 3.7/
│   │   └── components.ini
│   └── ...
└── ...

По умолчанию сайт документации имеет несколько пространств, которые определяют стадию (stage) готовности документации:

  • draft — собранная документация изначально попадает в это пространство. Данная сборка позволяет получить отчет сборки и информацию об исходном репозитории документации;

  • approved — перевод в пространство approved означает, что документация прошла внутреннее согласование и готова к внутренней приемке и публикации;

  • release — перевод в пространство release означает доступность документации для пользователей.

Каждый продукт может быть самостоятельным или включать в себя компоненты. Для перевода документации в нужное пространство, необходимо в файле components.ini продукта поставить соответствующий тег:

Стадия (stage)

Тег

draft

отсутствует

approved

approved

release

release

Пример components.ini для продукта с кодом PIF:

[PIF 1.0.0 release] # Раздел продукта в формате: код версия теги
common # Общая документация на продукт
PINF: 1.0.0 # Компонент, который есть в продукте (<COMPONENT-CODE>: <COMPONENT-VERSION>)
GDOC: 1.0.0 # Каждый компонент и его версия указываются на новой строке

[PIF 1.1.0 approved]
common
PINF: 1.1.0
GDOC: 1.1.0

[PIF 1.2.0]
common
PINF: 1.2.0
GDOC: 1.2.0

Установка тега release на головной элемент продукта (например, [PIF 1.0.0 release]) означает, что все элементы этой секции (общая документация и компоненты) должны быть доступны пользователям.

Важно

Головным элементом может быть только продукт - его трехбуквенный код и версия.

Установка тега release на отдельные элементы внутри головного (например, PINF: 1.0.0 release) означает, что только помеченные тегом release комплекты документации будут доступны пользователям.

Это действие может выполнять только релизный менеджер, контролирующий публикацию (список таких сотрудников указан в поле release-managers в doc-config.ini). Коммит с добавлением тега release, сделанный не релизным менеджером, будет отклонен автоматически.

Описание doc-config.ini:

[env]                                                     # Правила сборки
stage: draft, approved, release                           # Пространство для публикации. Доступны: draft - документация в разработке, approved - документация прошла внутренние согласования, release - готовая документация для пользователей
package: <PACKAGE-1>, <PACKAGE-2>, ..., <PACKAGE-N>       # Состав комплекта документации
audience: <AUDIENCE-1>, <AUDIENCE-2>, ..., <AUDIENCE-N>   # Целевая аудитория

# Пользователи, которые могут устанавливать тег release для публикации контента
release-managers:       user1,
                        user2

# Правила группировки документов
# [Имя группы документов]
[Общие документы]
# имя-директории-с-разделом-документации-в-репозитории: отображаемое-на-сайте-название-раздела
about:                  Описание
architecture:           Детальная архитектура
pmi:                    Программа и методика испытаний
release-notes:          Примечания к релизу
sizing:                 Методика расчета сайзинга
deployment-diagrams:    Диаграммы развертывания

[Руководства]
installation-guide:     Руководство по установке
administration-guide:   Руководство по системному администрированию
developer-guide:        Руководство прикладного разработчика
operators-guide:        Руководство оператора
security-guide:         Руководство по безопасности

[*]
*:      {title}

[Дополнительная документация]
*:      {title}

[Справочники API]
apis:   {title}