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

Технология сборки

Наложение слоев

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

  1. В базовой директории сборки размещаются два каталога: core и overlay.
  2. В каталоге core размещается базовая документация, которая может быть подключена как внешняя зависимость (например, git submodule).
  3. В каталоге overlay размещается специфический для данной сборки контент.
  4. В рабочую директорию копируется содержимое core.
  5. В рабочую директорию копируется содержимое overlay, перезаписывая все файлы, относительный путь которых внутри overlay совпадет с каким-либо файлом из core.

В результате в рабочей директории сборки получается контент из core, в котором заменены файлы, присутствующие в overlay. Если в overlay файла нет -- в сборку попадет файл из core.

Такое наложение позволяет переопределить контент, сохранив размещение статей, а значит -- все ссылки на них их других статей, неважно идут они из статьей core, или из статей overlay. В результате, адаптация контента может быть локализована в рамках той статьи, которая требует адаптации, без необходимости делать технические корректировки в других статьях.

Важно

Так как наложение директорий core и overlay производится только при сборке, ссылки из статей в overlay на статьи в core не будут кликабельны в IDE, которое ничего не знает о том что какие-то директории будут при сборке оказываться наложенными друг поверх друга.

Локальная сборка OpenSource-инструментами

Сборка документации осуществляется утилитой YFM-Docs.

Порядок установки YFM-Docs описан на вводной странице документации по этой утилите.

Для сборки OpenSource документации YDB нужно выполнить команду:

yfm -i <source_dir> -o <output_dir> --allowHTML

Где:

Сборка занимает несколько секунд, и не должна выводить сообщений об ошибках в лог (stdout).

В качестве source_dir можно задавать . (точку), если команда yfm вызывается непосредственно из каталога source_dir, например:

yfm -i . -o ~/docs/ydboss --allowHTML

Для просмотра собранной локально документации можно открыть каталог из браузера, или воспользоваться простым web-сервером, встроенным в Python:

python3 -m http.server 8888 -d ~/docs/ydboss

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

В этой статье: