Основные понятия

Три основные сущности, которыми оперирует Собирака, — проект, документ и страница.

Проект состоит из одного или нескольких документов, каждый из которых состоит из одной или нескольких страниц.

Проект #

Проект — это совокупность всех файлов, доступных Собираке во время сборки. Обычно под проект выделяется одна директория, и в её корне находится файл конфигурации, с помощью которого Собирака находит все другие файлы.

В проект могут входить:

Пути к дочерним директориям, из которых Собирака загружает те или иные файлы, выбирает технический писатель, составляющий файл конфигурации.

Благодаря концепции проекта возможно обеспечить переиспользование настроек и файлов, даже если из разных документов одного проекта собираются полностью независимые PDF-файлы.

Документ #

Документ — это набор страниц, которые вместе представляют собой документацию на определённую тему на определённом естественном языке (например, английском). Как правило, если для набора страниц требуется независимое оглавление — то их стоит объединить в отдельный документ.

При сборке PDF каждый документ становится отдельным PDF-файлом, а при сборке HTML — дочерней директорией.

Когда в проект входит несколько документов, они идентифицируются по языку текста и кодовому имени.

  • Язык текста (свойство lang) — обозначение языка согласно стандарту ISO 639-1. Например, вы можете указать для одного документа язык “ru”, а для другого “en”.

  • Кодовое имя (свойство codename) — короткое наименование документа. Например, вы можете разделить свой проект на документы с кодовыми именами “user-manual” и “admin-manual”.

Если в проекте присутствуют и разные языки, и разные документы на этих языках, то для обозначения конкретного документа используется идентификатор документа — запись из языка и кодового имени через слеш. Например: “ru/admin-manual”. Такой идентификатор, в частности, можно передать команде сборки PDF, чтобы выполнить сборку конкретного документа.

Документы с одинаковым кодовым именем, но разными языками считаются языковыми версиями одной и той же документации. Например, если в проекте есть документы “ru/user-manual” и “en/user-manual”, Собирака может сгенерировать виджет для переключения языка в HTML-документации.

Страница #

Страница — это часть документации, покрывающая какую-либо одну тему. Чаще всего одна страница зачитывается из одного исходного файла (и при сборке HTML также становится отдельным HTML-файлом). У каждой страницы есть заголовок и содержимое в одном из поддерживаемых форматов: Markdown или ReST. На страницу ведёт отдельная ссылка в оглавлении соответствующего документа.

В некоторых случаях количество сгенерированных страниц может отличаться от количества исходных файлов: например, Собирака может генерировать дополнительные индексные страницы для папок (см. Директории и индексные файлы).

Основной способ идентификации страниц внутри Собираки — это путь к соответствующему исходному файлу. Этот путь используется при обработке всех внутренних ссылок. Две страницы из разных документов, имеющие одинаковый путь внутри своих документов, считаются языковыми версиями друг друга.

Файлы, из которых будут сгенерированы страницы, загружаются в соответствии с настройками paths.root, paths.include и paths.exclude, а также файлами _nav.yaml.