Использование приложения#

Термины#

Argo Workflows — это контейнерный движок рабочих процессов в среде Kubernetes. Argo Workflows является частью продукта GetDocs, и все workflow, определенные в нем, имеют отношение к обработке документации.

Workflow — это главная сущность Argo Workflows, определяющая порядок действий для выполнения рабочего процесса и сохранение его состояния (аналог Jenkins job).

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

Распределение продуктов по категориям на главной странице сайта выполняется автоматически. Сортировка категорий происходит по алфавиту. Названия категорий и описания продуктов задаются в Продуктовом учете.

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

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

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

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

Интерфейс release и approved пространства выглядит следующим образом:

Интерфейс release и approved пространства

Элемент

Описание

Кнопка переключения в полноэкранный режим Кнопка выхода из полноэкранного режима

Переключение в полноэкранный режим и обратно

Кнопка переключения на темную тему Кнопка переключения на светлую тему

Переключение на темную/светлую тему

Кнопка обращения в техподдержку

Обратиться в техподдержку

Поле поиска

Поле ввода поискового запроса. В текущей версии реализован полнотекстовый поиск в пределах комплекта документации на продукт

Кнопка выхода

Выйти из сервиса

Кнопка сворачивания меню Кнопка разворачивания меню

Сворачивание и разворачивание боковой панели с меню

Кнопка вызова AI-ассистента

Вызов AI-ассистента

Интерфейс draft пространства имеет дополнительные кнопки для разработчика документации:

Интерфейс draft пространства

Элемент

Описание

Кнопка перехода в Argo Workflows

Открыть Argo Workflows

Кнопка получения отчета валидации

Открыть подменю, в котором доступны кнопки для открытия и скачивания отчета

Блок информации об исходных файлах документации

Информация об исходных файлах собранной документации: имя репозитория, ветки и хеш коммита (срез репозитория, из которого собрана документация). По нажатию на этот блок происходит переход в репозиторий документации для внесения исправлений

AI-ассистент#

Для более удобного поиска по сайту можно воспользоваться AI-ассистентом. Откройте чат с ассистентом, нажав кнопку в правом нижнем углу, и введите запрос. Поиск производится с учетом текущего контекста:

  • когда открыта разводящая страница со всеми комплектами документации, поиск производится по всей документации:

    AI поиск по всей документации

  • когда открыта документация продукта, поиск производится по текущему комплекту:

    AI поиск по документации продукта

Подготовка репозитория документации#

  1. Сконфигурируйте структуру документации.

  2. (Опционально) При наличии настройте API документацию.

  3. (Опционально) Добавьте документ в определенную группу для отображения на сайте.

Конфигурация комплекта документации#

  1. Разместите исходные файлы документации в папку documentation.

  2. Создайте в корне репозитория с исходными файлами документации файл doc-config.ini со следующей структурой:

    # Тип поставки.
# Тип "std" означает стандартную сборку комплекта документации.
# Это обязательная строка.
[std]

# Код компонента/продукта, к которому относится документация.
# Каждый продукт может быть самостоятельным или включать в себя компоненты.
# Продукты должны иметь трехбуквенные коды, а компоненты - четырехбуквенные.
# Это обязательная строка.
code: PIF

# Nexus GroupID для сборки архива с документацией.
# Обязательно для продукта. Для компонента это поле не нужно добавлять.
groupId: CI90000100_pif

# Версия компонента/продукта.
# Данная версия используется в URL документации на сайте, а также для сборки архива с документацией.
# Это обязательная строка.
version: 1.0.0
 
# Переменные.
# Использование в исходных файлах: {{ varname1 }}
# varname1: value1
# varname2: value2
  
# Исключения.
# Данные файлы не будут участвовать в сборке документации.
# Пути указываются через запятую, можно использовать glob-паттерны.
# exclude_patterns: dir1, glob/*, dir2

  3. Перенесите файлы ресурсов (изображения, видео, анимации и прочий вспомогательный контент не в Markdown формате) в папку resources. Обратите внимание, что данная папка требуется для каждого каталога документации в репозитории. Например, если в репозитории есть директории с контентом user-guide и installation-guide, папка resources должна быть в каждой из них.

    Скорректируйте ссылки на ресурсы соответствующим образом.

  4. Добавьте файл index.md в каждую папку с документацией, которую необходимо отобразить на сайте. Данный файл является разводящей страницей раздела.

    • Если в папке находится только один файл, переименуйте его в index.md.

    • Если папка содержит несколько файлов, index.md должен отражать содержание радела - заголовок первого уровня с названием раздела, заголовок ## Содержание и список ссылок на файлы документации с учетом иерархической вложенности разделов. Ниже приведен пример данного файла:

      <!-- ↓ название текущего раздела. -->
# Руководство по установке

<!-- ↓ обязательный заголовок. -->
## Содержание

<!-- ↓ ссылка на файл installation.md, который расположен в текущей директории и имеет заголовок "Установка". -->
* [Установка](installation.md)
  <!-- ↓ файлы, расположенные в текущей директории, которые должны отображаться как дочерние для раздела "Установка". -->
  * [На виртуальную машину](vm.md)
  * [В Kubernetes](k8s.md)
<!-- ↓ ссылка на файл update.md, который расположен в текущей директории и отображается на одном уровне с разделом "Установка". -->
* [Обновление](update.md)

Сборка API документации#

Сборку API документации можно провести тремя способами, в порядке приоритета:

Вручную#

Разместите API документацию в папку apis/ рядом с файлом info.json:

  • GRAPH_QL

    apis/                       // Директория с документацией на публичные API
└── <api-name>/             // Директория с документацией на версию публичного API
    ├── info.json           // Метаинформация об API
    └── graphql/
        └── index.graphql   // GraphQL API спецификация

  • GRPC

    apis/                       // Директория с документацией на публичные API
└── <api-name>/             // Директория с документацией на версию публичного API
    ├── info.json           // Метаинформация об API
    └── proto/
        └── index.proto     // gRPC API спецификация

  • JAVA

    apis/                       // Директория с документацией на публичные API
└── <api-name>/             // Директория с документацией на версию публичного API
    ├── info.json           // Метаинформация об API
    └── html/
        ├── index.html      // Корневой HTML файл Javadoc
        └── ...             // Остальные статичные файлы Javadoc

  • JSON_RPC

    apis/                       // Директория с документацией на публичные API
└── <api-name>/             // Директория с документацией на версию публичного API
    ├── info.json           // Метаинформация об API
    └── json/
        └── index.json      // JSON-RPC API спецификация (в соответствии с OpenRPC)

  • KAFKA

    apis/                       // Директория с документацией на публичные API
└── <api-name>/             // Директория с документацией на версию публичного API
    ├── info.json           // Метаинформация об API
    └── json/
        └── index.json      // Kafka API спецификация (в соответствии с AsyncAPI)

  • MQ

    apis/                       // Директория с документацией на публичные API
└── <api-name>/             // Директория с документацией на версию публичного API
    ├── info.json           // Метаинформация об API
    └── json/
        └── index.json      // MQ API спецификация (в соответствии с AsyncAPI)

  • OTHER

    apis/                       // Директория с документацией на публичные API
└── <api-name>/             // Директория с документацией на версию публичного API
    ├── info.json           // Метаинформация об API
    └── html/
        ├── index.html      // Корневой HTML файл прочей документации
        └── ...             // Дополнительные файлы прочей документации при их наличии

  • REST

    apis/                       // Директория с документацией на публичные API
└── <api-name>/             // Директория с документацией на версию публичного API
    ├── info.json           // Метаинформация об API
    └── json/
        └── index.json      // REST API спецификация (в соответствии с OpenAPI)

Из Git#

Укажите в apis/<api-name>/info.json в блоке repo информацию о репозитории, из которого нужно собрать API документацию. Для успешной настройки в репозитории в папке repo.apidir должен находиться соответствующий файл:

  • GRAPH_QL

    index.graphql или <любое-имя>.graphql, если он является единственным файлом с расширением .graphql в папке.

  • GRPC

    index.proto или <любое-имя>.proto, если он является единственным файлом с расширением .proto в папке.

  • JAVA

    pom.xml. В pom.xml должен быть добавлен плагин maven-javadoc-plugin.

    В GetDocs команда запуска javadoc зависит от pom.xml:

    • Если проект является агрегирующим (в pom.xml есть элемент <modules>) и версия maven-javadoc-plugin 3.1.0 или выше:

      mvn javadoc:aggregate-no-fork -Dadditionalparam=-Xdoclint:none -Ddoclint=none

    • В ином случае:

      mvn javadoc:javadoc-no-fork -Dadditionalparam=-Xdoclint:none -Ddoclint=none

    Для сборки используется Java 17, поэтому в итоге получается Javadoc с поиском, а не с боковым меню.

  • JSON_RPC

    index.json или <любое-имя>.json, если он является единственным файлом с расширением .json в папке.

  • KAFKA

    index.json или <любое-имя>.json, если он является единственным файлом с расширением .json в папке.

  • MQ

    index.json или <любое-имя>.json, если он является единственным файлом с расширением .json в папке.

  • OTHER

    index.html

  • REST

    index.json или <любое-имя>.json, если он является единственным файлом с расширением .json в папке.

Из Nexus CI#

Укажите в apis/<api-name>/info.json в блоке gav координаты (GroupId, ArtifactId, Version) API документации (при этом блок repo в info.json должен отсутствовать):

  • GRAPH_QL

    В хранилище артефактов описание GraphQL API должно быть представлено артефактом (текстовый файл) типа graphql (groupId: groupId API, artifactId: artifactId API, version: версия API, type: graphql).

    В info.json можно дополнительно указать классификатор в gav -classifier (необязательно).

  • GRPC

    В хранилище артефактов описание gRPC API должно быть представлено артефактом (текстовый файл) типа proto (groupId: groupId API, artifactId: artifactId API, version: версия API, type: proto).

    В info.json можно дополнительно указать классификатор в gav - classifier (необязательно).

  • JAVA

    В хранилище артефактов документация на публичные Java API должна быть представлена артефактом типа jar (groupId: groupId API, artifactId: artifactId API, version: версия API, type: jar, classifier: javadoc).

  • JSON_RPC

    В хранилище артефактов описание JSON-RPC API должно быть представлено артефактом типа json (groupId: groupId API, artifactId: artifactId API, version: версия API, type: json).

    В info.json можно дополнительно указать классификатор в gav -classifier (необязательно).

  • KAFKA

    В хранилище артефактов описание Message Broker API должно быть представлено артефактом типа json (groupId: groupId API, artifactId: artifactId API, version: версия API, type: json).

    В info.json можно дополнительно указать классификатор в gav - classifier (необязательно).

  • MQ

    В хранилище артефактов описание Message Broker API должно быть представлено артефактом типа json (groupId: groupId API, artifactId: artifactId API, version: версия API, type: json).

    В info.json можно дополнительно указать классификатор в gav - classifier (необязательно).

  • OTHER

    В хранилище артефактов описание Other API должно быть представлено артефактом типа zip (groupId: groupId API, artifactId: artifactId API, version: версия API, type: zip).

    В info.json можно дополнительно указать классификатор в gav - classifier (необязательно).

    Структура архива должна быть следующей:

    <api-name>.zip          // Архив с документацией на публичные API
└── html/
    ├── index.html      // Корневой HTML файл прочей документации
    └── ...             // Дополнительные файлы прочей документации если есть

  • REST

    В хранилище артефактов описание REST API должно быть представлено артефактом типа json (groupId: groupId API, artifactId: artifactId API, version: версия API, type: json).

    В info.json можно дополнительно указать классификатор в gav - classifier (необязательно).

В общем отчете будет информация о сборке API документации:

Информация о сборке API в отчете

Пример заполнения info.json:

{
    "type": "JAVA",
    "name": "Документация Java API",
    "description": "Документ, в котором описаны интерфейсы и классы Java API",
    "gav": {
        "groupId": "group.id.example",
        "artifactId": "artefact-id-example",
        "version": "1.0.0"
    },
    "repo": {
        "url": "ssh://git@mydomain:7998/code/api-demo.git",
        "commit": "577af2f44b9",
        "apidir": "/"
    }
}

Схема info.json:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "info.schema.json",
  "title": "Схема файла info.json",
  "type": "object",
  "properties": {
    "type": {
      "description": "Тип API",
      "type": "string",
      "enum": [
        "GRAPH_QL",
        "GRPC",
        "JAVA",
        "JSON_RPC",
        "KAFKA",
        "MQ",
        "OTHER",
        "REST"
      ]
    },
    "name": {
      "description": "Название API",
      "type": "string"
    },
    "description": {
      "description": "Краткое описание",
      "type": "string"
    },
    "gav": {
      "description": "Уникальный составной идентификатор версии API",
      "type": "object",
      "properties": {
        "groupId": {
          "type": "string"
        },
        "artifactId": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "classifier": {
          "type": "string"
        }
      },
      "required": [
        "groupId",
        "artifactId",
        "version"
      ]
    },
    "isOwn": {
      "description": "API разработано СБТ (не является заимствованным)",
      "type": "boolean",
      "default": true
    },
    "repo": {
      "description": "Репозиторий API",
      "type": "object",
      "properties": {
        "url": {
          "description": "SSH ссылка на репозиторий",
          "type": "string"
        },
        "commit": {
          "description": "Коммит",
          "type": "string"
        },
        "apidir": {
          "description": "Путь к API файлам",
          "type": "string"
        }
      },
      "required": [
        "url",
        "commit",
        "apidir"
      ]
    }
  },
  "required": [
    "type",
    "name",
    "description",
    "gav"
  ]
}

Добавление документа в определенную группу#

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

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

  1. Откройте файл index.md того документа, для которого задается группа.

  2. В начало файла добавьте группу:

    ---
group: Имя группы без кавычек
---
<!-- # Имя документа -->
<!-- Контент документа -->

Работа с workflows#

Обратите внимание

  • Получите ссылку для входа в Argo Workflow у системного администратора.

  • В поле NAMESPACE (пространство имен) должно быть указано значение getdocs, при другом значении возможна ошибка с запретом доступа.

Чтобы посмотреть список workflow, перейдите на страницу Workflows:

Страница Workflows

Чтобы отфильтровать список по создателю workflow, в поле LABELS укажите либо workflows.argoproj.io/creator-email=<почта-пользователя>, либо workflows.argoproj.io/creator-preferred-username=<логин-пользователя>:

Порядок запуска workflows#

Полный цикл работы с комплектом документации включает в себя следующие шаги:

  1. Подготовка репозитория документации к дальнейшей работе с workflows.

  2. Запуск workflow build-doc, который выполняет предварительную сборку и валидацию документации из исходных файлов в репозитории.

  3. Проверка отчета сборки и исправление ошибок сборки при необходимости.

  4. Внесение кода и версии успешно собранного комплекта документации в конфигурацию сайта.

  5. Запуск workflow build-site, который отобразит на сайте добавленный в конфигурацию комплект.

  6. (Опционально) Запуск workflow load-to-nexus для сборки архива с документацией и его загрузки в Nexus.

На любом этапе можно воспользоваться workflows проверки качества контента для валидации исходных файлов документации в репозитории:

Запуск workflow#

Workflow можно создать двумя способами - на странице Workflows или на странице Workflow Templates.

Workflows#

  1. Перейдите на вкладку Workflows.

  2. В поле NAMESPACE укажите getdocs.

  3. Нажмите кнопку SUBMIT NEW WORKFLOW.

  4. Выберите нужный workflow из списка:

    Создание нового workflow

  5. В появившейся форме не изменяйте поля Entrypoint и Labels, остальные заполните согласно описанию (появляется при наведении курсора на знак вопроса рядом с названием поля).

  6. Нажмите кнопку SUBMIT.

    Запуск нового workflow

Workflow Templates#

  1. Перейдите на вкладку Workflow Templates.

  2. В поле NAMESPACE укажите getdocs.

  3. Выберите нужный workflow из списка:

    Создание нового workflow template

  4. Нажмите кнопку SUBMIT в интерфейсе шаблона.

  5. В появившейся форме не изменяйте поля Entrypoint и Labels, остальные заполните согласно описанию (появляется при наведении курсора на знак вопроса рядом с названием поля).

  6. Нажмите кнопку SUBMIT.

    Запуск нового workflow template

Сборка документации (build-doc)#

Данный workflow позволяет собрать документацию по ссылке репозитория. Сборка происходит изолированно от общего сайта, поэтому документация появится там только тогда, когда дополнительно будет выполнен workflow build-site.

  1. Запустите workflow build-doc, указав необходимые параметры:

    Параметр

    Описание

    Пример

    repo_url

    Ссылка на репозиторий документации

    * docdev/a-paradigm
    * https://my-domain.ru/bitbucket-ci/projects/DOCDEV/repos/a-paradigm/browse
    * https://my-domain.ru/bitbucket-ci/scm/docdev/a-paradigm.git
    * ssh://git@my-domain:7998/docdev/a-paradigm.git

    repo_branch

    Ветка репозитория документации (если не указана, то используется ветка по умолчанию)

    * master
    * release/1.2.3

    repo_commit

    Коммит репозитория документации (имеет приоритет над веткой)

    * 3a561531d0a
    * b4e15bde1bbea2170f8de3d7d6136c5a3caf2407

    doc_dir

    Путь до папки с документацией в репозитории. Указывается относительно корня репозитория. Если пусто, то собирается папка, в которой расположен doc-config.ini. Если в репозитории несколько doc-config.ini (несколько комплектов документов), то нужно указывать путь до нужного doc-config.ini

    * documentation
    * path/to/docs

    code

    Код продукта/компонента (имеет приоритет над кодом в doc-config.ini)

    * PIF
    * GDOC

    version

    Версия продукта/компонента (имеет приоритет над версией в doc-config.ini)

    * 1.2.3
    * 3.2.1

  2. Когда workflow выполнится (т.е. когда корневой узел графа станет зеленым), нажмите на узел графа с названием report-draft-std-ext.html.
    Справа появится предпросмотр отчета.

  3. Чтобы открыть отчет на всю страницу, нажмите внизу кнопку REPORT-DRAFT-STD-EXT.HTML.

Отчет сборки документации

По умолчанию на данном этапе также происходит валидация документации. Подробнее работа с данным отчетом описана в разделе Работа с отчетом сборки документации.

Чтобы посмотреть все созданные отчеты сборки (все комбинации <stage>-<package>-<audience>), выполните шаги из раздела Просмотр всех отчетов сборки.

Сборка сайта (build-site)#

Данный workflow позволяет собрать сайт согласно конфигурации из репозитория content-configuration.

  1. Актуализируйте конфигурацию сайта самостоятельно или обратитесь к администратору. Например, если был собран новый комплект документации, который необходимо отобразить на сайте, добавьте его параметры в конфигурацию.

  2. Запустите workflow build-site. Данный workflow не требует указания параметров.

  3. Когда workflow выполнится (т.е. когда корневой узел графа станет зеленым), нажмите на узел графа с названием report-draft-std-ext.html.
    Справа появится окно предварительного просмотра отчета.

  4. Чтобы открыть его на всю страницу, нажмите внизу на кнопку REPORT-DRAFT-STD-EXT.HTML.

Отчет сборки сайта

Чтобы посмотреть все созданные отчеты сборки (все комбинации <stage>-<package>-<audience>), выполните шаги из раздела Просмотр всех отчетов сборки.

Создание и загрузка дистрибутива в Nexus CD (load-to-nexus)#

Данный workflow позволяет создать и загрузить дистрибутив в Nexus CD.

  1. Убедитесь, что код и версия продукта добавлены в конфигурацию сайта.

  2. Убедитесь, что документация продукта собрана с помощью workflow build-doc и build-site.

  3. Запустите workflow load-to-nexus, указав необходимые параметры:

    Параметр

    Описание

    Пример

    code

    Код продукта

    PIF

    version

    Версия продукта

    * 1.2.3
    * 3.2.1

    group_id

    Параметр groupId (если не указан, то используется groupId из doc-config.ini)

    * CI90000181_docdev
    * CI90000082_pvgd

    is_dev_repo

    Если значение равно 1, то дистрибутив загружается в репозиторий в Nexus CI.
    Если значение равно 0, то загрузка идет в Nexus CD

    * 0
    * 1

  4. Когда workflow выполнится (т.е. когда корневой узел графа станет зеленым), нажмите на корневой узел графа, откройте вкладку INPUTS/OUTPUTS и найдите блок Parameters. В параметре link будет ссылка на архив, а в non_approved - список компонентов, которых нет в release пространстве.

Результат загрузки дистрибутива в Nexus

Валидация контента#

Базовая валидация документации (validate-doc)#

По умолчанию базовая валидация происходит на этапе сборки документации.

При необходимости провалидировать документацию без ее сборки воспользуйтесь workflow validate-doc.

  1. Запустите workflow validate-doc, указав необходимые параметры:

    Параметр

    Описание

    Пример

    repo_url

    Ссылка на репозиторий документации

    * docdev/a-paradigm
    * https://my-domain.ru/bitbucket-ci/projects/DOCDEV/repos/a-paradigm/browse
    * https://my-domain.ru/bitbucket-ci/scm/docdev/a-paradigm.git
    * ssh://git@my-domain:7998/docdev/a-paradigm.git

    repo_branch

    Ветка репозитория документации (если не указана, то используется ветка по умолчанию)

    * master
    * release/1.2.3

    repo_commit

    Коммит репозитория документации (имеет приоритет над веткой)

    * 3a561531d0a
    * b4e15bde1bbea2170f8de3d7d6136c5a3caf2407

    doc_dir

    Путь до папки с документацией в репозитории. Указывается относительно корня репозитория. Если пусто, то собирается папка, в которой расположен doc-config.ini. Если в репозитории несколько doc-config.ini (несколько комплектов документов), то нужно указывать путь до нужного doc-config.ini

    * documentation
    * path/to/docs

    validation_rules_branch

    Ветка репозитория правил валидации (если не указана, то используется ветка master)

    * master
    * ropo

  2. Когда workflow выполнится (т.е. когда корневой узел графа станет зеленым), нажмите на узел графа с названием report.html.
    Справа появится окно предварительного просмотра отчета.

  3. Чтобы открыть его на всю страницу, нажмите внизу кнопку REPORT.HTML.

Результат валидации документации

Подробнее работа с данным отчетом описана в разделе Работа с отчетом сборки документации.

Валидация изображений (validate-doc-images)#

Базовые правила валидации также применимы для проверки изображений в документации.

Данный AI-валидатор анализирует изображения во всем комплекте документации, считывает с них текст и применяет к нему стандартные проверки.

Чтобы выполнить валидацию изображений, выполните следующие действия:

  1. Запустите workflow validate-doc-images, указав необходимые параметры:

    Параметр

    Описание

    Пример

    repo_url

    Ссылка на репозиторий документации

    * docdev/a-paradigm
    * https://my-domain.ru/bitbucket-ci/projects/DOCDEV/repos/a-paradigm/browse
    * https://my-domain.ru/bitbucket-ci/scm/docdev/a-paradigm.git
    * ssh://git@my-domain:7998/docdev/a-paradigm.git

    repo_branch

    Ветка репозитория документации (если не указана, то используется ветка по умолчанию)

    * master
    * release/1.2.3

    repo_commit

    Коммит репозитория документации (имеет приоритет над веткой)

    * 3a561531d0a
    * b4e15bde1bbea2170f8de3d7d6136c5a3caf2407

    doc_dir

    Путь до папки с документацией в репозитории. Указывается относительно корня репозитория. Если значение не задано, то собирается папка, в которой расположен конфигурационный файл doc-config.ini. Если в репозитории несколько конфигурационных файлов (несколько комплектов документов), укажите путь до нужного doc-config.ini

    * documentation
    * path/to/docs

    validation_rules_branch

    Ветка репозитория правил валидации (если не указана, то используется ветка master)

    * master
    * ropo

    config_file

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

    doc-config-pif.ini

  2. Когда workflow выполнится (т.е. когда корневой узел графа станет зеленым), нажмите на узел графа с названием report.html.
    Справа появится окно предварительного просмотра отчета.

  3. Чтобы открыть его на всю страницу, нажмите внизу кнопку REPORT.HTML.

Валидация системных требований (validate-doc-software)#

В GetDocs доступна проверка корректности указания системных требований в документации.

Предусловия

  • В репозитории с правилами валидации существует файл software.yaml. В файле размещаются списки с именами и версиями разрешенного и запрещенного стороннего программного обеспечения. Уточните данную информацию у администратора системы.

  • В репозитории с документацией руководство по установке расположено в папке installation-guide.

  • В репозитории с документацией существует файл system-requirements.md. В файле в свободной форме перечислено программное обеспечение (ПО), необходимое для корректной работы продукта или его функций.
    Обратите внимание, данный валидатор не поддерживает проверку автоматически сгенерированных системных требований.

Данный AI-валидатор выполняет следующие проверки:

  • Сверка упомянутого в тексте документации ПО со списком разрешенного и запрещенного.

    Валидатор анализирует полный комплект документации и обнаруживает все упоминания стороннего ПО. Далее проверяет, упомянуто ли найденное программное обеспечение в списке разрешенного или запрещенного (в файле software.yaml) и выдает соответствующую ошибку:

    • Упомянутая версия отличается от разрешенной: Версии разрешенного ПО нет в списке: <SoftwareName>. Обратитесь к юристам.

    • Упомянутое ПО найдено в списке запрещенного: Запрещенное ПО: <SoftwareName>.

    • Упомянутое ПО не найдено в списках разрешенного и запрещенного: Похоже на неизвестное ПО: <SoftwareName>. Убедитесь, что это действительно ПО. Если это так, обратитесь к юристам.

  • Сверка упомянутого в тексте документации ПО с перечисленным в системных требованиях к продукту.

    Валидатор анализирует полный комплект документации и обнаруживает все упоминания стороннего ПО. Далее проверяет, упомянуто ли найденное программное обеспечение в файле с описанием системных требований к продукту (system-requirements.md) и выдает соответствующую ошибку, если нет: ПО, которое не заявлено в системных требованиях: <SoftwareName>.

  • Проверка, что все стороннее программное обеспечение упомянуто в Руководстве по установке.

    Валидатор анализирует файл с описанием системных требований к продукту (system-requirements.md) и обнаруживает все упоминания стороннего ПО. Далее проверяет, все ли ПО упоминается в файлах в папке installation-guide. Если ПО указано в системных требованиях, но в руководстве по установке не упоминается, валидатор выдает следующую ошибку: ПО из системных требований, которое не упоминается в РУ: <SoftwareName>.

Чтобы выполнить валидацию системных требований, выполните следующие действия:

  1. Запустите workflow validate-doc-software, указав необходимые параметры:

    Параметр

    Описание

    Пример

    repo_url

    Ссылка на репозиторий документации

    * docdev/a-paradigm
    * https://my-domain.ru/bitbucket-ci/projects/DOCDEV/repos/a-paradigm/browse
    * https://my-domain.ru/bitbucket-ci/scm/docdev/a-paradigm.git
    * ssh://git@my-domain:7998/docdev/a-paradigm.git

    repo_branch

    Ветка репозитория документации (если не указана, то используется ветка по умолчанию)

    * master
    * release/1.2.3

    repo_commit

    Коммит репозитория документации (имеет приоритет над веткой)

    * 3a561531d0a
    * b4e15bde1bbea2170f8de3d7d6136c5a3caf2407

    doc_dir

    Путь до папки с документацией в репозитории. Указывается относительно корня репозитория. Если значение не задано, то собирается папка, в которой расположен конфигурационный файл doc-config.ini. Если в репозитории несколько конфигурационных файлов (несколько комплектов документов), укажите путь до нужного doc-config.ini

    * documentation
    * path/to/docs

    config_file

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

    doc-config-pif.ini

  2. Когда workflow выполнится (т.е. когда корневой узел графа станет зеленым), нажмите на узел графа с названием report.html.
    Справа появится окно предварительного просмотра отчета.

  3. Чтобы открыть его на всю страницу, нажмите внизу кнопку REPORT.HTML.

GetDocs позволяет генерировать DOCX и PDF файлы из исходных кодов документации.

  1. Запустите workflow print-doc, указав необходимые параметры:

    Параметр

    Описание

    Пример

    code

    Код продукта

    PIF

    version

    Версия продукта

    * 1.2.3
    * 3.2.1

    documents

    Список документов, которые надо создать, через запятую. Если список пуст, то создаются все документы из комплекта

    administration-guide*,user-guide*

    include_components

    Если в параметре code передан код продукта, и текущий параметр равен yes, будут также созданы выгружены документы включенных в продукт компонентов

    * yes
    * no

    format

    Формат выгружаемых файлов

    * pdf
    * docx

    package

    Формат пакета с документами

    std

  2. Когда workflow выполнится (т.е. когда корневой узел графа станет зеленым), нажмите на узел графа с названием docs.zip и загрузите архив с выгруженными документами.

Работа с отчетом сборки документации#

Отчет может иметь один из следующих статусов:

  • error Красный — Есть ошибки
    В документации обнаружены критические ошибки, которые необходимо исправить. При наличии ошибок (error) сборка завершается при обнаружении первой ошибки. Ее необходимо исправить, а затем запустить сборку заново.

  • warning Желтый — Есть замечания
    В документации обнаружены ошибки, которые следует исправить для публикации в release, но они некритичны для отображения документации в draft.
    При наличии только замечаний (warning) сборка проходит до конца.

  • ok Зеленый — ОК
    Ошибок и замечаний нет, сборка валидна.

Отчет содержит активные ссылки на место обнаружения ошибки в репозитории с номером строки в файле.

Правила валидации хранятся в репозитории content-validation.

Примечание
Если валидация комплекта документации выполняется больше 10 минут, рекомендуется в большие файлы комплекта документов, которые не предназначены для публикации, добавить <!-- vale off -->. Также это можно делать в накопительных длинных документах в то место документа, с которого нужно остановить валидацию (не проверять контент, относящийся к старым версиям).

Просмотр всех отчетов сборки#

Дополнительно можно посмотреть все созданные отчеты сборки (все комбинации <stage>-<package>-<audience>):

  1. Нажмите на корневой узел графа.

  2. Откройте вкладку INPUTS/OUTPUTS.

  3. Нажмите на иконку артефакта reports внизу страницы:

    Просмотр всех созданных отчетов сборки

  4. Нажмите на страницу отчета. Ссылка на собранный сайт будет внутри отчета.

Просмотр ошибок#

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

  1. Перейдите на страницу нужного workflow.

  2. Нажмите на красный не корневой узел графа.

  3. Откройте вкладку SUMMARY и внизу нажмите кнопку LOGS.

Откроется окно с логами, в котором будет видна строка с ошибкой — в строке будет слово | ERROR |:

Ошибка в логах сборки

Перезапуск workflow#

  1. Перейдите на страницу нужного workflow и нажмите кнопку RESUBMIT в интерфейсе workflow.

  2. Если нужно перезапустить workflow с другими параметрами, выберите опцию Override Parameters и измените значения.

  3. Нажмите кнопку RESUBMIT в форме.

Перезапуск workflow