This repository provides examples of DocC for Swift package, covering the process from creation to deployment
Apple says...:
For Swift packages, place the documentation catalog in the same folder as your library’s source files for DocC to associate the catalog with the library.
Add DocC Catalogue by following the instructions:
- Go to Project Navigator in Xcode and Select the Source/{TARGET_NAME} folder.
- Right click > New File... > Open File Template Selector.
- In the Documentation Section, select Documentation Catolog Template and click Next.
- Change the file name if necessary.
- Go to Settings > Pages > Build and deployment.
- Set Source to "GitHub Actions".
# Set up GITHUB_TOKEN permission to deploy to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
environment:
# Mandatory settings for GitHub Pages
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
xcodebuild docbuild -scheme {TARGET_NAME} \
-derivedDataPath /tmp/docbuild \
-destination 'generic/platform=iOS';
$(xcrun --find docc) process-archive \
transform-for-static-hosting /tmp/docbuild/Build/Products/Debug-iphoneos/{TARGET_NAME}.doccarchive \
--hosting-base-path {REPOSITORY_NAME} \
--output-path docs; # export to the path: docs
echo "<script>window.location.href += \"/documentation/{TARGET_NAME}\"</script>" > docs/index.html
If you use docc-plugin
:
swift package --allow-writing-to-directory {OUTPUT_PATH} \
generate-documentation --target {TARGET_NAME} \
--disable-indexing \
--transform-for-static-hosting \
--hosting-base-path {REPOSITORY_NAME} \
--output-path {OUTPUT_PATH}
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
# Upload files in `/docs` path
path: 'docs'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1
Problem
macos-latest
doesn't have Xcode15 (the latest version of Xcode is 14.1).
Solution
Specify macOS to 13 and Xcode to 15:
jobs:
deploy:
runs-on: macos-13 # latest macOS version
steps:
- name: Setup Xcode version
uses: maxim-lobanov/setup-xcode@v1 # to specify xcode version
with:
xcode-version: '15.0'
Reason When you go to Settings > Environment > GitHub Protection rule, it should be set to "main". Therefore, the production rule doesn't allow the PR branch to be deployed.
Reference
- Go to Settings > Pages > Build and deployment.
- Set Source to "Deploy from a branch".
- Select "main", "/docs" as "Branch".
- Click Save.
- Add dependency to Package.swift:
dependencies: [
.package(url: "https://github.com/apple/swift-docc-plugin", branch: "main"),
],
- Use
docc-plugin
command in Terminal:
$ swift package --allow-writing-to-directory {OUTPUT_PATH} \
generate-documentation --target {TARGET_NAME} \
--disable-indexing \
--transform-for-static-hosting \
--hosting-base-path {REPOSITORY_NAME} \
--output-path {OUTPUT_PATH}
Placeholder | Example |
---|---|
OUTPUT_PATH | ./docs |
TARGET_NAME | PackageDocCExample |
REPOSITORY_NAME | package-docc-example |
Command | Description |
---|---|
--allow-writing-to-directory {OUTPUT_PATH} |
Allow writing to the path where the output should be located |
generate-documentation --target {TARGET_NAME} |
Generate documentation for the target |
--disable-indexing |
Disable indexing |
--transform-for-static-hosting |
Transform for static hosting. It generates css, html files, not doccarchive file |
--hosting-base-path {REPOSITORY_NAME} |
Set up the base path for hosting |
--output-path {OUTPUT_PATH} |
The path where the output will be located |
- Commit & Push
Refer to GENERATE_DOCS.sh.
chmod +x ./GENERATE_DOCS.sh
./GENERATE_DOCS.sh