Сборка документации
Технология сборки
Наложение слоев
Сборка любого варианта документации осуществляется по одном шаблону:
- В базовой директории сборки размещаются два каталога:
core
иoverlay
. - В каталоге
core
размещается базовая документация, которая может быть подключена как внешняя зависимость (например, git submodule). - В каталоге
overlay
размещается специфический для данной сборки контент. - В рабочую директорию копируется содержимое core.
- В рабочую директорию копируется содержимое 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
Где:
source_dir
- директория, куда склонировано содержимое https://github.com/ydb-platform/ydb/tree/main/ydb/docsoutput_dir
- директория, куда будет выполнена генерация HTML-файлов
Сборка занимает несколько секунд, и не должна выводить сообщений об ошибках в лог (stdout).
В качестве source_dir
можно задавать .
(точку), если команда yfm вызывается непосредственно из каталога source_dir
, например:
yfm -i . -o ~/docs/ydboss --allowHTML
Для просмотра собранной локально документации можно открыть каталог из браузера, или воспользоваться простым web-сервером, встроенным в Python:
python3 -m http.server 8888 -d ~/docs/ydboss
При запущенном таким образом сервере собранная локально документация доступна по ссылкам:
- http://localhost:8888/ru - на русском языке
- http://localhost:8888/en - на английском языке