Building docs programmatically

This tutorial explains how to use the Swiftinit API to build documentation programmatically. You can use this to propagate changes to your documentation to Swiftinit from a CI pipeline, or some other tool.

Setting up GitHub webhooks

You can add a GitHub webhook to your project’s repository to notify Swiftinit when you publish new release (or prerelease) tags.

We recommend using webhooks whenever organization policy allows it. Webhook notifications are not only faster and require less manual intervention from developers, but are also exempt from the normal user rate limits.

Configuring the webhook

On your repository’s settings page, navigate to the Webhooks tab and click the Add webhook button. Use the settings below to configure the webhook.

Choose the Let me select individual events option and select the Branch or tag creation event. Deselect the Pushes event, and ensure that the Active checkbox is checked.

Swiftinit only accepts webhook notifications from GitHub’s official IP addresses. Therefore, there is no need to configure a webhook secret.

If you set up the webhook correctly, GitHub will send a ping event to Swiftinit, and you should see a response under Recent Deliveries resembling the following.

Access-Control-Allow-Origin: *
Content-Length: 26
Content-Type: text/plain; charset=utf-8
Host: swiftinit.org

Ignored event type 'ping'

Authenticating with the API

To use the API, you must first generate an API key from your account settings page. You also need your User ID, which is shown at the top of the same page.

To authenticate, pass the authorization header with the scheme Unidoc, and the value formatted as \(User ID)_\(API key).

An example of the header format is given below.

Authorization: Unidoc 4297524282_184d38185839950a

All API requests must be sent to https://api.swiftinit.org.

Requesting builds

You can request builds for a specific package and version by POSTing to the /ref endpoint. Set the content-type to application/x-www-form-urlencoded.

Structure

"""
/ref/\(PACKAGE)/\(REF)/build
"""

The PACKAGE name can be any valid alias of the package of interest. The REF name must match the name of the git tag you want to build. For example, if you want to build the tag v1.0.0, you must use the string v1.0.0 and not 1.0.0.

Example

The example below requests a build for version 510.0.2 of the SwiftSyntax package.

curl -v \
    -H "authorization: Unidoc 4297524282_184d38185839950a" \
    -H "content-type: application/x-www-form-urlencoded" \
    -H "content-length: 0" \
    -X POST \
    https://api.swiftinit.org/ref/swift-syntax/510.0.2/build

A successful build request will return a 303 See Other response pointing to the current canonical name of the package.

Do not manually build the documentation for a different version of the same package while a CI pipeline is running; this may displace or interfere with the CI build.

Observing documentation state

Users who want to export articles to their own content management system can use the documentation state API to check the state of the generated docs.

Structure

"""
/ref/\(PACKAGE)/\(REF)/state
"""

The documentation state endpoint has a similar structure to the build endpoint. It returns a JSON object of type Unidoc.EditionStateReport describing the current state of the package.

Example

curl \
    -H "Authorization: Unidoc 4297524282_184d38185839950a" \
    https://api.swiftinit.org/ref/swift-syntax/510.0.2/state

{"id":1,"build":{"stage":1},"phase":"ASSIGNED_CLONING_REPOSITORY"}

When the documentation is ready to be exported, the graph field will contain an object with a single field encoding the SHA-1 hash of the git commit the documentation was generated from, and the phase field will contain the string ACTIVE.

{
    "id": 42,
    "volume": "swift-syntax:510.0.2",
    "build": {},
    "graph": {"commit": "303e5c5c36d6a558407d364878df131c3546fad8"},
    "phase": "ACTIVE"
}

When rebuilding branches, it is likely that the branch already has ACTIVE documentation, so you should check that the git commit matches the one you expect.

Documentation state is very complex and there are many edge cases that are of little interest to CI users. To make it easier for CI clients to understand the state of the documentation, the server computes a simplified Phase description suitable for CI clients.