ScyllaDB University Live | Free Virtual Training Event
Learn more
ScyllaDB Documentation Logo Documentation
  • Server
  • Cloud
  • Tools
    • ScyllaDB Manager
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
  • Resources
    • ScyllaDB University
    • Community Forum
    • Tutorials
Download
ScyllaDB Docs ScyllaDB Sphinx Theme Deployment Production deployment

Caution

You're viewing documentation for a previous version of ScyllaDB Sphinx Theme. Switch to the latest stable version.

Production deployment¶

We use GitHub Pages and GitHub Actions to make the documentation publicly available.

On this page, you will learn:

  • How to deploy to GitHub Pages.

  • How to set up a custom domain.

  • How to read build error messages.

  • How to re-run a workflow.

  • How to disable GitHub Pages.

Available workflows¶

The toolchain provides the following workflows 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.

docs-links.yaml

Looks for broken links once a week. If there are broken links, it creates an issue in the same repository with the list of affected links.

Caution

If you modify these workflows in your repository, you will need to maintain the changes. So instead, we recommend you to open an issue in the sphinx-scylladb-theme repository so that all projects can benefit from the improvements you made.

Installation¶

To install the workflows:

  1. Copy the workflows named docs-*.yaml from .github/workflows to your project. The project’s directory structure should look like the following:

    project-name/
      ├── .github/
      |   ├── workflows/
      |   |   ├── docs-pages.yaml
      |   |   ├── docs-pr.yaml
      |   |   ├── docs-links.yaml
    
  2. If the default branch is not master or the docs are not under the docs folder, the workflows to match the project configuration. For example:

    on:
    push:
        branches:
        - master # edit this line
        paths:
        - "docs/**" # edit this line
    
  3. Commit and push the changes to GitHub (default branch).

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

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

Tip

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

Setting up a custom domain¶

Note

Setting up a custom domain requieres access to scylladb.com DNS configuration. Contact us in Slack #scylla-docs channel to set this configuration for you.

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. Verify the domain name to restrict its usage only on ScyllaDB organization repositories. To do so, follow the steps in Verifying your domain with GitHub.

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

Reading error messages¶

Docs builds usually fail when there is a critical error or warning in the documenation syntax.

To get the specific error message:

  1. Hover the that you will see next to the commit message, and click on Details.

    ../_images/build-error.png
  2. Search for “warning” and “error” in the box you will find at the top right of the screen.

    ../_images/build-log.png

You should see the error messages highlighted.

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.

Was this page helpful?

PREVIOUS
Deployment
NEXT
Pull requests previews
  • Create an issue
  • Edit this page

On this page

  • Production deployment
    • Available workflows
    • Installation
    • Setting up a custom domain
    • Reading error messages
    • Re-running a workflow
    • Disabling GitHub Pages
ScyllaDB Sphinx Theme
  • 1.3
    • 1.8
    • 1.7
    • 1.6
    • 1.5
    • 1.4
    • 1.3
    • 1.2
    • 1.1
  • Getting started
    • Toolchain
    • Installation
    • Quickstart
  • Configuration
    • Template options
    • Page options
    • Multiversion options
    • Markdown support
    • Redirects support
    • Search support
    • Troubleshooting
  • Commands
  • Deployment
    • Production deployment
    • Pull requests previews
  • Examples
    • Admonitions
    • Collapse
    • Code blocks
    • Glossary
    • Headings
    • Hero box
    • Includes
    • Images
    • Labels
    • Links
    • Lists
    • Panel box
    • Substitutions
    • Tables
    • Tabs
    • Text
    • TOC
    • Topic box
    • Versions
  • Upgrade guides
    • Migrating from 1.2 to 1.3
    • Migrating from 1.1 to 1.2
    • Migrating from 1.0 to 1.1
    • Migrating from 0.x to 1.0
    • Changelog
  • Contribute
    • Contribute to the documentation
    • Contribute to the theme
    • Source Code
Docs Tutorials University Contact Us About Us
© 2025 ScyllaDB | Terms of Service | Privacy Policy | ScyllaDB, and ScyllaDB Cloud, are registered trademarks of ScyllaDB, Inc.
Last updated on 01 Apr 2025.
Powered by Sphinx 7.4.7 & ScyllaDB Theme 1.8.6
Ask AI