Sphinx ScyllaDB Theme 1.0 is now released πŸ₯³
Learn more


This quickstart walks you through the steps required to add the documentation toolchain to a project hosted on GitHub.

Step 1: Download the sample projectΒΆ

  1. Copy the docs and .github directories from the repository scylladb/sphinx-scylladb-theme to the root directory of the project where you want to set up docs. The project’s directory structure should look like the following:

       β”œβ”€β”€ pyproject.toml
       β”œβ”€β”€ .github/workflows/docs-pages@v2.yaml
       β”œβ”€β”€ .github/workflows/docs-pr@v1.yaml
       β”œβ”€β”€ docs/
       β”‚   β”œβ”€β”€ _utils/
       β”‚   |   β”œβ”€β”€ deploy.sh
       β”‚   |   β”œβ”€β”€ redirect.sh
       β”‚   |   β”œβ”€β”€ setup.sh
       β”‚   β”œβ”€β”€ source/
       β”‚   β”œβ”€β”€ Makefile


    If you already have docs in the project under an existing docs directory, move the doc files to the docs/source directory.

  2. Create the file docs/pyproject.toml under the new docs folder. Copy the contents from the pyproject.toml template.

Step 2: Configure the themeΒΆ

  1. Edit the file docs/source/conf.py file to suit the project needs (e.g. install new extensions, edit navigation links, …). For more information, see Configuration.

  2. If you don’t already have a .gitignore file in the project, place one in the root directory and include /docs/_build and /source/.doctrees in it. If you already have a .gitignore file, add both paths to the file.

Step 3: Preview the site locallyΒΆ

  1. Delete or adapt the sample documentation files under docs/source.

  2. From the command line, run make preview within the docs folder. Fix any warnings raised by Sphinx.

  3. Once the docs build without errors, open to preview the generated site.

Step 4: Deploy to GitHub PagesΒΆ

To deploy the documentation site, see GitHub Pages Configuration.