Exploring MusicKit and Apple Music API
Unlock the full power of MusicKit & Apple Music APIs in your apps with the best guide! Use code musickit-blog for a limited-time 35% discount!
Apple introduced the DocC documentation compiler to create rich API reference documentation and interactive tutorials for your app, framework, or package that looks similar to what Apple uses for documentation.
When you change something in your framework or package, like adding a new feature or updating the syntax, you ideally want the documentation to update automatically. If you already have a CI/CD setup, you can add a small script that updates the documentation and pushes it to the repository.
This post focuses on creating a script ideal for automatically updating static hosted documentation. The example uses my library, MusadoraKit, which has the documentation hosted on GitHub Pages.
Generating Documentation
You can generate the documentation using a simple command that takes multiple parameters. The major two are the target’s name and the package’s base path. You also specify the directory as the output path, and if you use GitHub Pages, you can save the documentation in the docs folder.
For example, MusadoraKit is the target of my package with the base path as MusadoraKit. The command for generating the documentation becomes:
swift package --allow-writing-to-directory ./docs \
generate-documentation --target MusadoraKit \
--disable-indexing \
--transform-for-static-hosting \
--hosting-base-path MusadoraKit \
--output-path ./docs
You can try generating the documentation yourself locally to try it out and see if it passes.
Pushing the Documentation
The next part is to push the documentation back into the repository after successfully building and testing the package. These are simple git commands, but you need to provide the Personal Access Token to authorize writing to the repository. You can store the PAT as a secret variable on your CI and then reference it later in the script in the workflow configuration file.
I am using Codemagic as the CI provider, and the script should work across any provider.
name: Update DocC Documentation
script: |
swift package --allow-writing-to-directory ./docs \
generate-documentation --target MusadoraKit \
--disable-indexing \
--transform-for-static-hosting \
--hosting-base-path MusadoraKit \
--output-path ./docs
git add .
git commit -m "[skip ci] Update DocC Documentation"
git remote set-url origin https://rudrankriyam:$token@github.com/rryam/MusadoraKit.git
git pull
git push origin main
I am setting the origin URL as “username:TOKEN@github.com/path_to_package.git”. Also, pushing back to the repository may trigger another build if you are triggering on push; to avoid that, you include the [skip ci] in your commit message.
You pull from the repository just in case anything has been updated since the workflow started on the virtual machine.
Conclusion
And that’s it! With every commit, you can get freshly updated documentation automatically! I forgot to update the docs before a release, so I needed to automate this mundane process.
The workflow file for MusadoraKit here contains the script for building, testing, and updating the documentation for the package on every commit.
If you have a better approach, feel free to tag @rudrankriyam on Twitter! I love feedback and appreciate constructive criticism.
Thanks for reading, and I hope you’re enjoying automating your docs!
Exploring MusicKit and Apple Music API
Unlock the full power of MusicKit & Apple Music APIs in your apps with the best guide! Use code musickit-blog for a limited-time 35% discount!