Ведение правил валидации контента#

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

Структура правил в репозитории content-validation имеет следующую структуру:

.
└── content-validation/
    ├── styles/
    │   ├── <STYLE-1>/
    │   │   ├── <RULE-11>.yaml
    │   │   ├── <RULE-12>.yaml
    │   │   ├── ...
    │   │   └── <RULE-1N>.yaml
    │   ├── <STYLE-2>/
    │   │   ├── <RULE-21>.yaml
    │   │   ├── <RULE-22>.yaml
    │   │   ├── ...
    │   │   └── <RULE-2N>.yaml
    │   ├── ...
    │   ├── <STYLE-N>/
    │   │   ├── <RULE-N1>.yaml
    │   │   ├── <RULE-N2>.yaml
    │   │   ├── ...
    │   │   └── <RULE-NN>.yaml
    │   └── Vocab/
    │       ├── <VOCAB-1>/
    │       │   ├── accept.txt
    │       │   └── reject.txt
    │       ├── <VOCAB-2>/
    │       │   ├── accept.txt
    │       │   └── reject.txt
    │       ├── ...
    │       └── <VOCAB-N>/
    │           ├── accept.txt
    │           └── reject.txt
    ├── .vale.ini
    └── rules/
        ├── software.yaml
        └── md.yaml

Базовые правила#

Данные правила проверяются при сборке документации (workflow build-doc), при запуске базовой валидации контента (workflow validate-doc) и валидации изображений (workflow validate-doc-images).

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

• проверки правил руководства по стилю, внутреннего глоссария, проверки на наличие запрещенной информации и прочие проверки, реализуемые с помощью поиска по регулярным выражениям инструментом Vale (узел workflow validate-doc-with-vale),

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

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

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

Vale проверки#

Ведение файла конфигурации .vale.ini и создание правил валидации описано в официальной документации Vale:

• Configuration

• Styles

Правила проверки Markdown-разметки#

Для проверки соответствия разметки документации стандартным правилам Markdown GetDocs использует библиотеку Markdownlint. Конфигурация правил проверки задается в файле md.yaml и имеет следующую структуру:

# Default state for all rules
default: true

# Path to configuration file to extend
extends: null

# MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md001.md
MD001: true

# MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md003.md
MD003:
  # Heading style
  style: "consistent"

# MD004/ul-style : Unordered list style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md004.md
MD004:
  # List style
  style: "consistent"

# ...

Подробная информация о правилах и их конфигурации приведена в официальной документации.

Правила проверки системных требований#

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

Одна из проверок проверяет, что упомянутое в документации программное обеспечение не является запрещенным и что версия этого ПО рекомендована к использованию. Список запрещенного ПО и рекомендуемых версий хранится в файле software.yaml в репозитории content-validation. Ниже приведен пример данного файла:

# в блок можно добавить слова, которые ошибочно распознаются валидатором, как ПО
ignore:
  - 'CLOSED|ERROR|FAIL|URL'
  - 'List|Map|String|Session|Data|Context|Value|Service'

# в блоке перечисляются рекомендуемые версии для разрешенного ПО в формате 'SoftwareName: version1, version2'
allow:
  - Kubernetes: 1.0, 1.21, 1.24
  - Prometheus: 2.21.0, 2.31
  - РЕД ОС: 7.3

# в блоке перечисляется нерекомендуемое ПО
prohibit:
  - (Atlassian )?BitBucket
  - (Red ?Hat )?Enterprise Linux

Значения в каждом блоке поддерживают регулярные выражения.