Сборка в HTML

sobiraka web [--config CONFIG] [--output OUTPUT] [--hide-index-html]

Эта команда собирает HTML-документацию из файла CONFIG (по умолчанию — sobiraka.yaml) в директорию OUTPUT (по умолчанию — build/web).

Если директория, указанная в OUTPUT, существует и содержит файлы (например, результат сборки предыдущей версии), то после сборки они будут удалены или перезаписаны.

Если сборка завершится неудачно, то в конечной директории могут остаться перемешанными как старые, так и новые файлы. Не публикуйте результаты неудачных сборок.

Структура выходной директории #

Если в проекте несколько документов, то каждый документ собирается в отдельную поддиректорию, названную в соответствии с настройкой web.prefix. Главная страница каждого документа размещается в файле index.html соответствующей поддиректории. Единой главной страницы для многодокументного проекта не создаётся.

В поддиректорию под названием _resources (или под другим названием, заданным в web.resources_prefix) копируются все изображения, использованные в документации. В частности, если все места, где использовалось определённое изображение, оказались исключены из сборки с помощью условных конструкций Jinja, то по умолчанию изображение скопировано не будет. Вы можете переопределить это поведение для конкретных изображений, включив пути к ним в настройку web.resources_force_copy.

В поддиректорию под названием _static копируются все статические файлы из темы оформления. Если в теме оформления используются файлы стилей SASS, то собранные из них готовые стили в формате CSS будут также скопированы в _static.

Собирака формирует все ссылки между страницами и все служебные пути (например, пути к изображениям) таким образом, чтобы они не зависели от расположения директории. Готовую документацию можно опубликовать по адресу https://docs.example.com/, а можно по адресу https://example.com/docs/, и она будет работать одинаково.

По умолчанию каждая ссылка содержит полное имя файла, на который она ссылается — даже если это имя index.html. Это важно для просмотра документации локально, но обычно считается избыточным при размещении на веб-хостингах, поскольку они автоматически поддерживают для ссылок вида section/index.html более короткие варианты вида section/. Чтобы Собирака использовала короткие пути, необходимо передать ей аргумент --hide-index-html. Мы рекомендуем передавать этот аргумент при сборке финальной версии сайта.