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

InstallationΒΆ

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:

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

    Note

    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 http://127.0.0.1:5500/ to preview the generated site.

Step 4: Deploy to GitHub PagesΒΆ

To deploy the documentation site, see GitHub Pages Configuration.