Запуск Xcode DocC без Apache Server/ (.htaccess)

В документации DocC «Распространение документации среди внешних разработчиков» Apple предоставила документацию для размещения архива документации на вашем веб-сайте . К сожалению, когда я открываю .doccarchive/index.html, Я просто получаю белую страницу. Они показали только руководство для серверов Apache. Они указали, используя .htaccess файл и используя RewriteRule .* SlothCreator.doccarchive/$0 [L] для перезаписи URL-адресов, когда пользователь посещает страницу документации.

Есть ли способ открыть веб-приложение документации без запуска сервера Apache? (Я не хочу делать какую-либо конфигурацию для конкретной машины, например, изменять /etc/hosts). Было бы идеально разместить его как статический сайт (например, на страницах Github, страницах Cloudflare, Netlify и т. Д.).

Источник

3 ответа

На данный момент я не думаю, что есть возможность разместить его как статический сайт.

Однако довольно легко разместить его на Netlify с настроенным файлом .toml:

      [build]
publish = "ProjectName.doccarchive/"
###### Change it to your doccarchive file's name

[[redirects]]
from = "/documentation/*"
status = 200
to = "/index.html"

[[redirects]]
from = "/tutorials/*"
status = 200
to = "/index.html"

[[redirects]]
from = "/data/documentation.json"
status = 200
to = "/data/documentation/projectname.json"
###### Change it to name in ProjectName.doccarchive/data/documentation/...
# often just all lowercase of your project name

[[redirects]]
force = true
from = "/"
status = 302
to = "/documentation/"

[[redirects]]
force = true
from = "/documentation"
status = 302
to = "/documentation/"

[[redirects]]
force = true
from = "/tutorials"
status = 302
to = "/tutorials/"
Источник

Теперь это задокументировано в SwiftDocCPluginруководство:

Преобразование для статического хостинга

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

Пример

Предупреждение

Вы увидите несколько Unfortunatelyв этом ответе. Я настоятельно рекомендую вам избегать использования DocC по причинам, описанным ниже. Если вы найдете обходные пути для них, дайте мне знать :). С точки зрения сравнения, DocC конкурирует со многими успешными генераторами статических сайтов и платформами документации с открытым исходным кодом (Docusaurus) и не очень хорошо справляется.

Шаги

  • Добавьте SwiftDocCPlugin в свой Package.swift:
      .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
  • Создайте сайт, запустите:
      # Update to your target, from `Package.swift`
TARGET_NAME=SlothCreator
OUTPUT_DIR=docs
swift package --allow-writing-to-directory $OUTPUT_DIR \
    generate-documentation \
    --target $TARGET_NAME \
    --disable-indexing \
    --output-path $OUTPUT_DIR \
    --transform-for-static-hosting
  • cd docs
  • Запустите его локально :
    • Вы можете запустить сервер для обслуживания ваших файлов: запустите python3 -m http.server.
    • Откройте сайт в браузере: http://localhost:8000/documentation/target_name/
    • Предупреждение: ему по-прежнему нужен веб-сервер, а веб-сайт работает не очень хорошо. Если вы посетите http://localhost:8000, вы получаете сообщение об ошибке: The page you’re looking for can’t be found.Вы не можете просто открыть index.htmlстраница без сервера.
  • Разверните его с помощью страниц GitHub или рабочих сайтов Cloudflare:
    • При развертывании об этом позаботятся, поскольку страницы GitHub, рабочие сайты Cloudflare обслуживают эти страницы. К сожалению, это не будет работать с Cloudflare Pages, так как он не может создавать документацию Swift.
  • К сожалению , пути не настраиваются: /<output-path-specified-by-command-line>/documentation/<target-name>, например, это может быть: localhost:8000/documentation/slothcreator/
  • К сожалению , вы должны закоммитить сгенерированные файлы документации в git. Документы Apple показали команду: git add docsа также git commit -m "Update GitHub pages documentation site.". Это связано с тем, что такие сервисы, как Github Pages, Cloudflare Workers Sites, не могут создать ваш сайт за вас.
  • К сожалению , эта сгенерированная папка ( docs/) составляет 31 МБ и содержит ненужные файлы и большие неоптимизированные активы. Для некоторых сервисов, например Cloudflare Workers Sites, вам необходимо загружать весь веб-сайт при каждой публикации.
  • К сожалению , вам нужно перегенерировать и зафиксировать все файлы отдельно, если вы хотите поместить их по разным путям, так как вам нужно использовать другую команду. См. комментарии в build.sh . Это означает, что это не 31 МБ, а N x 31 МБ, где N — количество ваших сайтов.
Источник

Обновление для Xcode 13.3

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

В своем последнем сообщении в блоге я описал несколько шагов для развертывания docarchive приложения/пакета DocC через страницы GitHub .

Приходилось решать несколько вопросов:

  1. Убедитесь, что в созданных URL-адресах документов и размещенных базовых путях учитывается регистр.
  2. Использовать xcodebuild -project ModularSlothCreator.xcodeproj -scheme ModularSlothCreator -parallelizeTargets docbuildпостроить модульный архив документации.
  3. Использовать transform-for-static-hostingфлаг, предоставленный doccli ${xcrun docc} transform-for-static-hosting ...

Для получения более подробной информации и сценария CI не стесняйтесь ссылаться на сообщение в блоге.

Источник
Другие вопросы по тегам