Методические указания для документации

Документация пользователя размещается на GitHub Pages и собирается на базе темы Just the Docs для Jekyll. Она развёртывается автоматически с помощью GitHub Action’а при каждом изменении документации в папке docs, объединённом в ветку main.

Вклад должен соответствовать Методическим указаниям для контрибьюторов и подаваться через pull request.

Содержание

  1. Методические указания для документации
    1. Содержание
    2. Сборка локально
    3. Требования
      1. Ресурсы
      2. Порядок навигации
      3. Стиль
      4. Содержимое страниц
        1. Оглавление (TOC)

Сборка локально

Подробнее об установке Jekyll и его зависимостей см. в документации Jekyll.

  1. Перейдите в корень документации — папку docs.

  2. Соберите сайт и запустите локальный сервер: bundle exec jekyll serve.

  3. Откройте http://localhost:4000.

Требования

Ресурсы

Все ресурсы должны размещаться внутри репозитория, а не на внешних ресурсах со вставленными ссылками.1 Даже если ресурс используется самим приложением RimSort, его копию нужно включить в docs/assets. Таким образом, документация репозитория будет самодостаточной.

Порядок навигации

Порядок навигации определяется важностью страниц и схожестью их заголовков. Например, «Методические указания для документации» и «Методические указания для контрибьюторов» должны стоять рядом в навигации, поскольку у них похожие структура и названия. Это делается для удобства использования и эстетики.

Стиль

Навигационная информация (например, Файл > Настройки) и имена файлов (например, About.xml) должны всегда оформляться как код.

Содержимое страниц

Оглавление (TOC)

Родительские страницы автоматически генерируют оглавление со списком своих дочерних страниц. Не отключайте эту возможность.

Большинство контентных страниц должны содержать оглавление (TOC). Оглавление должно идти первым заголовком второго уровня после основного заголовка страницы и относящегося к нему содержимого.

Заголовок страницы и заголовок оглавления не должны попадать в само оглавление — их следует помечать .no_toc. Все остальные заголовки страницы должны быть включены в оглавление.

Заголовок оглавления следует помечать .text-delta, чтобы применить к нему соответствующий стиль.

Чтобы сгенерировать оглавление, вставьте следующий код (markdown):

## Содержание
{: .no_toc .text-delta }

1. TOC
{:toc}

  1. Некоторые ресурсы со старого вики сохранены и не размещаются внутри самого репозитория. ↩