Как опубликовать на GitHub с помощью Docc?

Question

У меня есть пакет SPM, размещенный на https://github.com/janodev/foobar.

Как создать документацию с помощью Docc и разместить ее на GitHub?

Answer 1

1. Установите Xcode 13.3 beta 1 или 2. Не Beta 3 , потому что она несовместима со Swift-DocC.
2. Добавьте Swift-DocC в качестве зависимости вашего пакета. Это будет выглядеть примерно так:

      let package = Package(
    platforms: [
        .iOS(.v15), .macOS(.v12)
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-docc-plugin", branch: "main"),
    ],
    targets: [
        // ...
    ]
)

3. Включить публикацию страницы в GitHub

• В репозитории GitHub перейдите в «Настройки» > «Страницы».
• Выберите ветку: главная, папка: /docs
• Нажмите Сохранить

4. Создание документов в каталоге ./docs.

      # note this is for GitHub hosting, with a specific target and base path 'Foobar'

# don’t forget to build or you’ll get blank pages
swift build

swift package \
 --allow-writing-to-directory ./docs \
 --target Foobar \
 generate-documentation \
 --output-path ./docs \
 --transform-for-static-hosting \
 --hosting-base-path foobar

⚠️ Значения параметров чувствительны к регистру.

5. Отправьте сгенерированную документацию в репозиторий.

Сайт появится на

      #       username          repository           target
https://janodev.github.io/foobar/documentation/foobar

---

Xcode 13.3 предоставляет Swift 5.6, необходимый для Swift-DocC , и возможность использовать DocC для приложений iOS. Однако Swift-DocC, похоже, не работает с приложениями на момент написания этой статьи. Я даже пытался написать поддельный пакет и передать обычные флаги компилятора для компиляции UIKit в терминале (см. ниже). Вероятно, это будет поддерживаться в будущем выпуске.

      -Xswiftc "-sdk" -Xswiftc "`xcrun --sdk iphonesimulator --show-sdk-path`" -Xswiftc "-target" -Xswiftc "x86_64-apple-ios15.2-simulator"

Если вы получите

      Error: The file “data” couldn’t be opened because there is no such file.

не забудьте добавить .macOS(.v12)к платформам пакета.