Swift documentation without long CI pipelines

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.

Slap some docstrings in your code

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 swift-build or xcodebuild — here we use xcodebuild . For example:

xcodebuild -scheme MyScheme -destination 'platform=iOS Simulator,name=iPhone 12 Pro' -sdk iphonesimulator

• The possible schemes that can be passed to scheme can be gotten with xcodebuild -list .
• We are using iphonesimulator rather than a real phone, and building for iPhone 12 Pro.
• You can also specify an arbitrary simulator like -destination 'generic/platform=iOS' — this StackOverflow answer details a few more options.

Make sure the module builds at this step.

Set up jazzy

The best way to set up jazzy is from .jazzy.yaml file. Create one:

touch .jazzy.yaml

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:

swift\_build\_tool: "xcodebuild"

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:

output: "public"

The complete file then is:

After it is set up, you can generate the docs just by running

jazzy

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 docs branch:

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 pages directive.

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!