Self-serve documentation builds on Swiftinit

This article explains how to build and publish your own documentation on Swiftinit.

How do Swiftinit documentation builds work?

Swiftinit builds documentation from GitHub repositories. Swiftinit does not mirror your code, so your GitHub repository is the source of truth for your documentation.

The basic steps to publish documentation on Swiftinit are:

  1. Create a git tag and push it to GitHub. The tag must be a valid semantic version, but there is no requirement for the package to actually follow semantic versioning.

  2. Request a tags fetch on Swiftinit. Swiftinit periodically crawls GitHub repositories based on popularity, but you can also request an immediate tags fetch through the web interface. Alternatively, you can set up a GitHub webhook to automatically notify Swiftinit about new release tags.

  3. Request a documentation build on Swiftinit. Once Swiftinit has imported at least one valid tag, you can request a documentation build through the web interface.

In the following sections, we will walk through how to verify a GitHub account, add a repository, request a tags fetch, and perform a documentation build.

Prerequisites

To use Swiftinit Self-serve, you need a GitHub account, and at least one public repository under your personal account, or an organization you are a member of, that contains a SwiftPM package. The package must be buildable with Swift 5.10 on Ubuntu Linux 22.04 LTS.

Verifying your GitHub account

To perform most actions on Swiftinit, you must have an existing GitHub account and verify with Swiftinit that you are the owner of the account.

Logging in with GitHub

To log in to Swiftinit through GitHub, visit swiftinit.org/login and click the Authenticate with GitHub button. This will redirect you to GitHub, where you can authorize Swiftinit to access your account.

Generating an API key

After logging in, you should activate your linked GitHub account by clicking on API keys ▸ Generate API key. For the purposes of this tutorial you will not need to interact with the API key, you only need to have generated it.

Importing a repository

You can add an unlimited number of repositories to Swiftinit.

To import a repository, fill out the Repositories ▸ Repo name form field, and click Index GitHub repository. If Swiftinit was able to find the repository, the site will redirect you to the tags page for the imported repository.

Importing a repository from a GitHub organization

Swiftinit now supports organization-aware permissions, allowing you to manage packages that are owned by a GitHub organization you are also a member of.

To use GitHub organizations with Swiftinit, you must first verify your membership on the Account settings page, under Organizations. Once you have verified your membership, you can import repositories from the organization by specifying the organization name in the Repositories ▸ Repo owner form field.

Importing tags

If your Swift package is popular and available under a free software license, there is a high chance the repository and its tags are already known to Swiftinit. If not, you can schedule a tags fetch by clicking on Package settings ▸ Request tags fetch. Tags fetching usually completes within a few seconds.

Once the tags appear on the tags page, you can request a documentation build.

Building documentation

To build documentation, click on Package settings ▸ Request build. This will take you to a form where you can further customize the build.

Platform preference

All documentation builds currently take place on Aarch64 Ubuntu Linux 22.04 LTS. You should leave the Build configuration ▸ Platform preference option blank, or set it to aarch64-unknown-linux-gnu. A successful build will also set the platform preference as it is now known to be compatible with the platform.

Observing build progress

All documentation builds take place on specialized build servers, and logged-in users can observe the state of the build on the tags page.

If the build servers are currently occupied, the build will enter a Queued state. Otherwise it will skip directly to the Started state.

When the build completes or fails, the builder will upload the logs to Swiftinit where you can view them under Package settings ▸ Build logs.

If the build succeeds, a symbol graph should appear under Package tags and Swiftinit will link and publish the documentation within a few seconds.

Going further

You may want to read the Export articles to your own blog with Swiftinit tutorial to learn how to generate rendered articles you can then republish on your own website.