FREE Virtual Training Event | April 22, 2021
Register Now >

Caution

You are reading an unstable version of this documentation. If you want up-to-date information, please have a look at 0.1.21 .

GitHub Pages

The theme uses GitHub Pages and GitHub Actions to make the documentation publicly available. The file .github/pages.yaml in your project defines how docs are published using GitHub Pages.

Most projects build and deploy a new site every time the default branch (master) receives an update. When multiversion is enabled, GitHub Pages builds docs for all versions listed in the file conf.py.

Enabling GitHub Pages

Note

You need to be logged in GitHub with Admin or Maintain repo permissions. If this is not the case, please ask the repo owner to invite you as a collaborator.

  1. Change html_baseurl setting in docs/conf.py for the future public URL of your site. For instance, we will use https://scylladb.github.io/sphinx-scylladb-theme.

  2. Create a new gh-pages empty branch. Run the commands in the root directory.

    git checkout --orphan gh-pages
# Warning: Be careful; the next command deletes all files inside the folder.
git rm -rf .
touch .nojekyll
git add .
git commit -m "Setup GitHub Pages"
git push origin gh-pages

  3. Open the repository Settings and scroll down to the “GitHub Pages” section.

  4. Select gh-pages branch.

  5. Wait a couple of minutes; it might take a while until GitHub applies the changes. If everything goes well, you will see the docs published under https://scylladb.github.io/<repository-slug>.

Disabling GitHub Pages

To disable the docs deployment temporarily, see Unpublishing a GitHub Pages Site.

Setting up a custom domain

Note

You need access to the domain DNS configuration.

Follow the next 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 docs/conf.py for the desired sub-domain name. For instance, we will use sphinx-theme.scylladb.com.

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