Sphinx ScyllaDB Theme 1.0 is now released 🥳
Learn more
Menu

Deployment

The theme uses GitHub Pages and GitHub Actions to make the documentation publicly available.

On this page, you’ll learn:

  • How to configure the workflows.

  • How to deploy to GitHub Pages.

  • How to set up a custom domain.

  • How to re-run a workflow.

  • How to disable GitHub Pages.

Available workflows

The toolchain provides the following GitHub Actions under the directory .github/workflows:

Filename

Description

docs-pages.yaml

Builds multi versioned docs every time the default branch (e.g. master) receives an update. If the build completes successfully, the workflow publishes the HTML version to GitHub Pages.

docs-pr.yaml

Builds the docs when the default branch receives a new pull request or when the pull request receives new commits. The purpose of this workflow is to make sure pull requests do not break the default branch after being merged.

Configuring the workflows

To configure the workflows:

  1. Ensure you have the workflows in your project under .github/workflows. If you have followed Getting Started to install the project, the workflows are already included in the documentation project by default. If this is not the case, you can download them from this link.

  2. Edit the workflows to match the project configuration if the default branch is not master or the docs are not under the docs folder. For example:

  3. Commit and push the changes to GitHub (default branch).

Enabling GitHub Pages

Once you push the workflows to the remote repository default branch, GitHub might take a couple of minutes to build and publish the site.

You can check the status of the build on GitHub. Under your repository name, click Actions.

If everything goes well, you will see the docs published under https://scylladb.github.io/<repository-slug>.

Setting up a custom domain

Follow the following steps to set up a custom domain:

  1. In the domain’s DNS configuration, create a new CNAME record that points <custom-sudomain>.scylladb.com to scylladb.github.io.

  2. Change html_baseurl setting in conf.py for the desired sub-domain name. For instance, we will use sphinx-theme.scylladb.com.

  3. Commit and push the changes to GitHub (default branch).

  4. Once the DNS changes propagate (<24 h), the docs will be accessible from the custom domain name.

Re-running a workflow

Re-running workflows is useful when:

  • The theme received an update. By re-running the last build manually, the documentation project will receive the latest version. Otherwise, the theme will be automatically updated when the default branch gets an update.

  • A previous version (branch or a tag) received a patch. Otherwise, the changes will not be reflected in production until the master branch gets an update.

To re-run a workflow see, Re-running a workflow.

Disabling GitHub Pages

To disable the docs deployment temporarily:

  1. Delete the workflows from .github/workflows, and push the changes.

  2. Disable GitHub Pages from the repository settings. For more information, see Unpublishing a GitHub Pages Site.