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

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

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

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

Результат выполнения workflow валидации

Базовая валидация включает в себя следующие типы проверок:

  • проверки содержимого на соответствие руководствам по стилю (validate-doc-with-vale),

  • проверки корректности Markdown-разметки (validate-doc-markdown), а также возможности корректного отображения этой разметки на сайте,

  • проверка возможности сжатия PNG-изображений (compress-images),

  • проверка сборки API-документации (transform-api).

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

  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

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

    * 1a111111a1a
    * a1a11aaa1aaaa1111a1aa1a1a1111a1a1aaa1111

    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

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

    * 1a111111a1a
    * a1a11aaa1aaaa1111a1aa1a1a1111a1a1aaa1111

    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

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

    * 1a111111a1a
    * a1a11aaa1aaaa1111a1aa1a1a1111a1a1aaa1111

    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.