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

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

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

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

   <!-- doc-config-ini-start -->
   # Тип поставки.
   # Тип "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, dir3/**/internal-file.md
   

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)