Убедитесь, что ваша документация всегда синхронизирована на веб-сайте и в кодовой базе.

В первой части этой статьи мы узнали, как мы можем создавать документацию для наших фреймворков Swift с помощью DocC.

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

Что мы узнаем:

Экспорт архива DocC

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

Чтобы экспортировать архив DocC, перейдите в раздел Продукты › Документация по сборке.

затем нажмите кнопку контекстного меню слева от имени корневой статьи вашей библиотеки внутри окна документа Xcode.

Затем выберите место для экспорта вашего архива

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

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

Для этого мы собираемся разместить документацию в Интернете, как и собственный веб-сайт документации Apple.

Мы будем использовать Github и Netlify для настройки нашего веб-сайта с документацией.

Если у вас уже есть свой пакет swift на Github, это хорошо, если нет, создайте репозиторий и переместите каталог пакетов swift на Github в качестве репозитория.

Генерация доархива из командной строки

Прежде чем двигаться вперед, нам нужно создать docarchive в папке docs внутри нашего каталога пакетов swift, чтобы docarchive можно было включить в наш репозиторий git, который будет использоваться позже для размещения сайта документации.

Чтобы создать docarchive из командной строки, выполните следующие команды из корневого каталога вашего пакета swift.

  1. Запустите следующий CMD, чтобы создать документальный архив в пользовательском расположении производных данных.
xcodebuild docbuild -scheme ElegantAPI -derivedDataPath ~/ElegantAPIBuild -destination 'platform=iOS Simulator,name=iPhone 12'

2. Мы скопируем сгенерированный docarchive по пути Docs/ElegantAPI.docarchive внутри нашего пакета swift, запустив:

cp -R `find ~/ElegantAPIBuild -type d -name 'ElegantAPI.doccarchive'` Docs/ElegantAPI.doccarchive

3. Нам нужно будет добавить /* /index.html 200 , так как docarchive построен поверх Vue.js, нам нужно это перенаправление, чтобы маршрутизация работала, выполнив следующую команду, мы создадим файл внутри нашего docarchive с именем _redirects, который затем будет использоваться маршрутизатором Vue.js для успешного перехода на нашу страницу документации.

echo "/* /index.html 200" >  Docs/ElegantAPI.doccarchive/_redirects

Теперь вы можете отправить эту папку на GitHub, добавив ее в git и отправив ее на Github.

Размещение документального архива на netlify

Теперь, когда наш репозиторий Github содержит наш docarchive, мы собираемся использовать netlify для размещения этого docarchive в качестве веб-сайта, docarchive уже генерирует все HTML и JS, необходимые для представления нашей документации в Интернете, нам просто нужно обслуживать их на сервере и для что мы будем использовать Netlify, поэтому, если у вас нет учетной записи в Netlify, вы можете создать ее по адресу: https://app.netlify.com/signup.

Вы можете зарегистрироваться с помощью GitHub.

Вам будет задано несколько вопросов, ниже приведен пример того, как вы можете его заполнить.

Вам будет представлена ​​страница настройки проекта, выберите импорт проекта:

Выберите свой GitHub в качестве исходного провайдера.

Выберите репозиторий GitHub вашего быстрого пакета:

Вам будет представлена ​​следующая форма: добавьте путь к каталогу публикации так же, как ваше местоположение docarchive в репозитории GitHub.

После этого вы увидите что-то похожее на скриншот ниже:

Вы можете перейти на свой размещенный сайт документации, нажав на верхнюю левую ссылку, в моем случае https://nervous-pike-2f8a3f.netlify.app, но вы не увидите документацию, а пустой экран, как показано ниже:

Чтобы увидеть вашу документацию, вам нужно будет изменить бит URL, как показано ниже:

https://nervous-pike-2f8a3f.netlify.app/documentation/ElegantAPI

Здесь вы можете изменить базовый URL-адрес и конечный путь в соответствии с вашим базовым путем и именем пакета.

Формат <base url>/documentation/<swift package name>

Теперь вы можете увидеть свой размещенный документ на измененном URL-адресе:

Изменение базового URL размещенного документа

Как вы могли заметить, netlify предоставляет нам случайно сгенерированный URL-адрес, но вы можете отредактировать URL-адрес, чтобы сделать его более удобочитаемым.

Для этого перейдите в настройки домена:

Затем нажмите на правую вкладку параметров и нажмите «Изменить имя сайта»:

Затем внутри поля добавьте предпочитаемое имя субдомена:

и вуаля! Теперь вы можете получить доступ к сайту по адресу:

https://elegantapi.netlify.app/documentation/ElegantAPI

Автоматизация сборки и развертывания docarchive с помощью bitrise

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

Это то, что мы собираемся автоматизировать в этом разделе с помощью Bitrise.

Пожалуйста, создайте учетную запись Bitrise, если у вас ее нет, здесь.

Создание приложения в bitrise

После того, как вы создали свою учетную запись, вам нужно будет добавить приложение на панель инструментов, нажав кнопку «Добавить новое приложение», чтобы добавить приложение на панель инструментов.

На следующем шаге вам будет предложено указать тип конфиденциальности приложения, вы можете выбрать частный или общедоступный для этой демонстрации, которую мы выбираем частный:

На следующем шаге bitrise попросит вас подключить ваш репозиторий от одного из предоставленных поставщиков репозиториев, в данном случае мы выбрали GitHub и наш репозиторий пакетов swift:

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

Нам не требуется доступ к частному репо, поэтому выберите «Нет, автоматически добавлять SSH-ключ».

Далее вам нужно будет указать ветку, из которой нужно взять код, в данном случае мы выбираем ветку по умолчанию «master»:

Bitrise попытается распознать тип вашего проекта. Но поскольку мы не настраиваем приложение для iOS, оно не сможет определить конфигурацию для нас:

Таким образом, мы выполним пользовательскую настройку для нашего конвейера CI:

Выберите «Другое/Вручную» в списке настроек и выберите стек macOS в раскрывающемся списке, затем нажмите «Я готов»:

Пропустите значок приложения и раздел веб-перехватчика и завершите настройку, нажав «Готово» в правом верхнем углу:

После того, как вы закончите настройку, вы сможете увидеть только что созданное приложение на панели инструментов:

Определение рабочего процесса CI

Нажмите на свое приложение и перейдите в раздел рабочего процесса, теперь мы определим здесь наш конвейер CI, вы увидите экран, как показано ниже:

Как видите, bitrise настроил для нас довольно много рабочих процессов, но нам не потребуются все они, так как мы не будем развертывать для bitrise. Вместо этого мы удалим шаг. Для этого нажмите «Развернуть в Bitrise», прокрутите вниз правый раздел и удалите шаг:

Теперь перейдите к шагу «Делай что-нибудь со скриптом» и вставьте следующий скрипт:

echo "Building Doc"
# Builds the docarchive with custom derive data path, change the scheme name to match your package here
xcodebuild docbuild -scheme ElegantAPI -derivedDataPath ~/ElegantAPIBuild -destination 'platform=iOS Simulator,name=iPhone 12'
#2 Copy the docarchive to correct place, change the path according to you package name
cp -R `find ~/ElegantAPIBuild -type d -name 'ElegantAPI.doccarchive'` Docs/ElegantAPI.doccarchive
#3 Writes necessary redirects
echo "/* /index.html 200" >  Docs/ElegantAPI.doccarchive/_redirects
#4 Git config needed to push back to git repo, replace with your git id and email
git config user.name "DominatorVbN"
git config user.email "[email protected]"
#5 Add the newly generated docarchive to git indexc and commit 
git add .
git commit -m "Archive Updated [skip ci]"
#6 Push back to the git repo, if your branch is other than master change accordingly
git push [email protected]:DominatorVbN/ElegantAPI.git HEAD:master

Этот скрипт отвечает за создание docarchive и отправку обновленного архива в репозиторий git.

Настройка вебхука для сборки netlify

Этот сценарий только обновит репозиторий git новым docarchive, но он не будет развернут для netlify для этого, мы настроим веб-перехватчик, чтобы сообщить netlify о повторном развертывании нашего сайта.

Для этого перейдите на панель инструментов netlify и перейдите к настройкам сборки:

Затем перейдите к «Сборка и развертывание» в правом боковом меню, перейдите к «Создать крючки» и нажмите «Добавить сборку крючков»:

Назовите хук сборки как bitrise и выберите master в качестве ветки по умолчанию для сборки:

Теперь скопируйте этот URL-адрес и добавьте к нему следующее:

curl -X POST

результирующая команда будет выглядеть так:

curl -X POST https://api.netlify.com/build_hooks/61db0cd86a3e78dfb669d325

Добавьте это к шагу скрипта в bitrise:

Введите CMD+S, чтобы сохранить рабочий процесс.

Настройка SSH в Bitrise

Нам нужно будет сделать немного больше настроек, чтобы иметь возможность вернуться в наш репозиторий Github, нам нужно будет настроить ключ ssh, который обеспечит доступ к нашему репозиторию Github, чтобы Bitrise CI мог отправить в наш репозиторий, перейдите в настройки вкладка вашего приложения в Bitrise:

Затем прокрутите вниз до настроек SSH:

Нажмите «Изменить пару ключей SSH», затем выберите «Создать пару ключей SSH»:

Скопируйте сгенерированный открытый ключ SSH в буфер обмена:

Перейдите на Github и перейдите к настройке с помощью верхней правой кнопки профиля:

Перейдите в раздел «Ключи SSH и GPH», затем нажмите «Новый ключ SSH»:

Вставьте скопированный открытый ключ и дайте ему имя, затем нажмите «Добавить ключ SSH»:

Настройка вебхука для GitHub

Как только это будет сделано, мы готовы настроить наш веб-перехватчик, который запустит сборку, когда мы отправим наш код на GitHub, чтобы настроить веб-перехватчик, перейдите к APP > Code > Incoming Webhooks и нажмите «Настроить автоматически»:

Это все настройки для тестирования конвейера, вы можете внести некоторые изменения в свой документ и отправить его на Github.

Вы можете увидеть, как работает ваша сборка, на панели инструментов Bitrise:

Это все для этой статьи. Спасибо за прочтение.

Want to Connect?
Reach out to me on Twitter, Linkedin.