Публикуем документацию DocC в виде сайта GitHub Pages

На WWDC 2021 Apple представила DocC. Это замечательный фреймворк для создания подробной справочной документации по API и интерактивных учебных пособий для проектов, сред или пакетов Swift. Благодаря специальному синтаксису DocC Markdown — разметке документации — компилятор может сам создавать документацию для Swift-проектов и отображать ее прямо в окне документации Xcode.

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

Создание архива DocC

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

Пример проекта представляет собой пакет Swift, и его можно редактировать в Xcode, открыв файл Package.swift. Реальные возможности пакета не так важны для этой статьи, но пакет содержит много исходных файлов с разметкой DocC внутри, которые используются для создания документации.

Чтобы скомпилировать документацию, выберите пункт меню «Продукт» (Product) в верхней строке меню, а затем нажмите «Создать документацию» (Build Documentation). Вы также можете использовать сочетание клавиш ^⇧⌘D. Окно документации открывается автоматически или доступно с помощью сочетания клавиш ⇧⌘0. Документация будет содержать специально созданную документацию для проекта, а разметка DocC будет отображаться так же красиво, как и в официальной документации Apple для разработчиков.

Чтобы экспортировать архив DocC, вы можете щелкнуть правой кнопкой мыши на Workspace Documentation для пакета (в данном случае SlothCreator) и выбрать экспорт. Это создаст файл .doccarchive, содержащий всю документацию, которую можно будет дополнительно обработать для размещения в виде сайта.

Вы также можете экспортировать архив DocC с помощью командной строки, что очень удобно, например, если вы хотите интегрировать этот шаг в конвейер CI/CD или рабочие процессы Xcode Cloud. Это можно сделать в терминале с помощью команды xcodebuild docbuild из папки проекта.

xcodebuild docbuild \
-scheme TARGET_NAME \
-derivedDataPath PATH_TO_SAVE_DERIVED_DATA_FOLDER \
-destination 'platform=iOS Simulator,name=iPhone 13'

В качестве scheme вы должны предоставить схему продукта вашего проекта. Затем вы должны указать derivedDataPath — производный путь к данным, в котором будет создан архив DocC. Например, вы можете создать папку на рабочем столе или в другом удобном для вас месте. Наконец, в качестве пункта назначения destination, нужно указать платформу, используемую для сборки. Архив будет создан в папке Build внутри derivedDataPath.

Создание файлов для статичного хостинга

Перед размещением архива DocC в качестве веб-сайта экспортированный файл .doccarchive необходимо обработать, чтобы преобразовать его содержимое для хостинга. Это еще не доступно из пользовательского интерфейса внутри Xcode, но, начиная с Xcode 13.3, это можно легко сделать и в командной строке. Чтобы убедиться, что это будет работать, перейдите в настройки Xcode и выберите  Command Line tools 13.3 на вкладке Locations.

Затем внутри Терминала вы можете использовать команду process-archive.

$(xcrun --find docc) process-archive \
transform-for-static-hosting PATH_TO_DOARCHIVE_FILE \
--output-path PATH_TO_SAVE_FILES \
--hosting-base-path URL_BASE_PATH

Вы должны указать путь к файлу .doccarchive, который был экспортирован из документации Xcode Workspace или создан с помощью инструментов командной строки. Затем output-path указывает путь, по которому будет сохранен архив процессов. Наконец, hosting-base-path — это базовый URL-адрес статического сайта, на котором вы размещаете документацию. Если вы используете GitHub, это может быть username.github.io/repository-name/, и в результате имя репозитория будет URL_BASE_PATH. В любом другом случае это должен быть базовый URL-адрес вашего сайта, например, domain.com.

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

Публикация документации DocC с помощью GitHub Pages

Популярным способом размещения статичных сайтов являются GitHub Pages или Gitlab Pages. Вы можете не только разместить любую статическую страницу, которую вы хотите, это имеет смысл и для размещения документации для вашего репозитория. Если в вашем репозитории GitHub размещен пакет Swift, соответствующая страница GitHub также может служить документацией.

Чтобы это запустить, вы должны включить функцию GitHub Pages для своего репозитория, перейдя к настройкам. На левой панели вы можете выбрать Pages. Затем вы можете выбрать ветку git, которую хотите использовать для размещения статического сайта. Это может быть интересно, если вы хотите использовать выделенную ветку только для документации. Затем вам предстоит выбрать папку, в которой будут находиться файлы для страницы. Имя папки по умолчанию — docs.

Если вы поместив файлы в эту папку внутри репозитория, GitHub автоматически развернет их как страницу с URL-схемой username.github.io/repository-name/.

Затем внутри папки проекта скопируйте файлы для статического хостинга в папку /docs. В качестве последнего шага зафиксируйте и отправьте изменения в репозиторий. Github автоматически развернет статический сайт через GitHub Pages.

Обратите внимание, что путь по умолчанию username.github.io/repository-name/ ничего не покажет. Это связано с характером сгенерированного сайта, который обслуживает любую документацию в подпапке /documentation. Необходимо добавить имя проекта или Package в нашем примере, чтобы получить правильную документацию.

Это связано с тем, что в одном архиве DocC может храниться документация по разным продуктам. Таким образом, конечный URL-адрес документации в нашем случае будет username.github.io/repository-name/documentation/slothcreator. Конечно, это можно дополнительно настроить, но это тема для другой статьи.

Источник