The awesomeness of CI is that docs and tests run automatically. Requiring that tests pass on merges is probably the most critical CI feature to large projects.
The pain of CI for Swift is that for simple things like generating documentation, we have to build the entire package/app, which usually makes our pipelines take forever.
If docs aren’t the most critical part your design, you can avoid using CI and push the docs manually to host your site. Here we will do it using jazzy.
Click on the method or class to document, then use
command-option-/ to insert a docstring template. A basic format is:
/// Description /// /// Discussion blah blah /// /// A new paragraph in discussion /// /// /// - **Parameters**: /// - param1: First parameter /// - param2: Second parameter /// - **Returns**: Returned thing
Figure out how to build your module from the command line =========================================================
Generating the docs with
jazzy requires that your module builds from the command line. You can use
xcodebuild — here we use
xcodebuild . For example:
xcodebuild -scheme MyScheme -destination 'platform=iOS Simulator,name=iPhone 12 Pro' -sdk iphonesimulator
schemecan be gotten with
iphonesimulatorrather than a real phone, and building for
iPhone 12 Pro.
-destination 'generic/platform=iOS'— this StackOverflow answer details a few more options.
Make sure the module builds at this step.
The best way to set up jazzy is from
.jazzy.yaml file. Create one:
To set up the config file, we must translate the build commands from before into the correct
YAML format. The complete list of options to put into this file can be found here:
jazzy --help config
First, specify that we want to use
xcodebuild in this case:
Next, set the arguments. The command from above translates to:
build\_tool\_arguments: - "-scheme" - "MyScheme" - "-destination" - "platform=iOS Simulator,name=iPhone 12 Pro" - "-sdk" - "iphonesimulator"
Finally, you specify other things like the output directory:
The complete file then is:
After it is set up, you can generate the docs just by running
from the command line. You should get the message to ensure it worked:
jam out ♪♫ to your fresh new docs in `public`
Host your pages on GitLab without CI ====================================
Sometimes you don’t have a project with many collaborators and you don’t care to set up long documentation pipelines. So you can just take that
public folder from the previous step and host it manually.
First, copy the
public folder from the last step somewhere outside the repo.
Next, switch to a dedicated
git checkout -b docs
Remove everything here (including an entry for the
public folder in your
.gitignore if it exists).
Then paste the
public folder from the last step into here.
Finally, add this super simple pipeline that literally just takes the public folder and hosts it using the usual
pages directive — in a new file called
.gitlab-ci.yml , add:
Note that this was modified from the original slightly — the
only directive is important for the
OK — you got me, we used CI.
But it isn’t building your package from scratch on some runner, it’s literally doing nothing and just taking your
public folder on the
docs branch and pushing it — so this isn’t a pipeline that’s taking all day.
Commit everything and push it:
git add . git commit -m "docs docs docs"
Hopefully you will see your pages pipeline fire in the GitLab CI console and your docs will appear.
Now have fun writing all those docstrings!