How to automate DocC documentation hosting with Github Pages
DocC is a toolset designed specifically for documenting Swift frameworks and packages. This article talks about automating building, exporting and hosting documentations using GitHub workflows and GitHub hosting.
Prerequisites
- A library thats well documented according to DocC syntaxes and standards.
- Basic Github workflow setup.
Github workflow Steps
Create a workflow file (.yml) inside Project/.github/workflows/
folder and follow the below steps to build the workflow.
- Checkout to the branch
- name: Checkout 🛎️
uses: actions/checkout@v3
actions/checkout@v3
is a GitHub action that allows you to fetch the source code or repository into your workflow's workspace. It creates a shallow clone of the repository, including only the most recent commit, for improved performance. You can use it to checkout a specific commit, branch, or tag from a remote repository and make it available for subsequent steps in your workflow.
2. Select required Xcode version
- name: Force Xcode 13.3.1
run: sudo xcode-select -s "/Applications/Xcode_13.3.1.app"
sudo xcode-select
is a command used on macOS to manage the location of Xcode command line tools. It allows you to set the default Xcode installation, install the command line tools, or verify their installation. Using sudo
grants administrative privileges for making system-level changes.
3. Install CocoaPods (optional, only if required)
- name: pod install
run: bundle exec pod install
4. Build DocC documentation
swift package resolve;
xcodebuild docbuild -workspace 'Project.xcworkspace' -scheme Project -derivedDataPath /tmp/docbuild -destination 'platform=iOS Simulator,name=iPhone 12';
echo "Archiving documentation..."
$(xcrun --find docc) process-archive \
transform-for-static-hosting /tmp/docbuild/Build/Products/Debug-iphonesimulator/Project.doccarchive \
--output-path docs \
--hosting-base-path '';
echo "** Archived documentation**"
echo "<script>window.location.href += \"tutorials/table-of-contents\"</script>" > docs/index.html;
When you execute xcodebuild docbuild -workspace
, Xcode will analyze your project or workspace and generate the associated documentation. This documentation typically includes API references, code comments, and other relevant information about the project.
When you execute $(xcrun --find docc) process-archive
, you are instructing the docc
tool to process a documentation archive. The documentation archive typically contains the necessary files and metadata required to generate documentation for a particular project or framework.
It’s worth noting that the specific behavior and available options for the xcodebuild docbuild
command may vary depending on the Xcode version and the structure of your project or workspace. It's recommended to consult the Xcode documentation or use the xcodebuild
command-line tool's help option (xcodebuild -help
) for more details on the available options and how to use them.
5. Upload Artefacts
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
# Upload only docs directory
path: 'docs'
The actions/upload-pages-artifact
action is designed to upload a directory of files as an artifact to the GitHub Pages branch. It is commonly used in CI/CD (Continuous Integration/Continuous Deployment) workflows to generate documentation, build websites, or any other static content that needs to be published to GitHub Pages.
By including this action in your GitHub Actions workflow, you can generate a directory of files and then use the actions/upload-pages-artifact
action to upload those files to the appropriate branch of your repository, which is typically the gh-pages
branch used for GitHub Pages.
6. Deploy to Github Pages
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1
actions/deploy-pages@v1
is a GitHub action that helps deploy static websites or web applications to GitHub Pages. It automates the process of pushing built artifacts to a specified branch or folder within the repository, making it easier to publish your site on GitHub Pages.
Full Github workflow
name: Deploy DocC Documentation to Github Pages
on:
# Runs on pushes targeting the master branch
push:
branches: ["master"]
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow one concurrent deployment
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
# One deployment deploy job since we're just deploying
deploy:
environment:
# Must set to this for deploying to GitHub Pages
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: macos-12
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Force Xcode 13.3.1
run: sudo xcode-select -s "/Applications/Xcode_13.3.1.app"
- name: pod install
run: pod install
- name: Build DocC
run: |
swift package resolve;
xcodebuild docbuild -workspace 'Project.xcworkspace' -scheme Project -derivedDataPath /tmp/docbuild -destination 'platform=iOS Simulator,name=iPhone 12';
echo "Archiving documentation..."
$(xcrun --find docc) process-archive \
transform-for-static-hosting /tmp/docbuild/Build/Products/Debug-iphonesimulator/Project.doccarchive \
--output-path docs \
--hosting-base-path '';
echo "** Archived documentation**"
echo "<script>window.location.href += \"tutorials/table-of-contents\"</script>" > docs/index.html;
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
# Upload only docs directory
path: 'docs'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1