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 Getting started Installation

Caution

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

Installation¶

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

Prerequisites¶

Before adding the documentation toolchain to a project, you will need to have installed:

  • Python 3.7 or later.

  • Poetry 1.12 or later.

Step 1: Download the sample project¶

  1. Copy the docs directory 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/
       ├── docs/
       │   ├── _utils/
       │   |   ├── redirects.yaml
       │   |   ├── deploy.sh
       │   ├── source/
       │   |   ├── conf.py
       │   |   ├── index.rst
       │   ├── Makefile
    

    Note

    If you already have docs in the project under an existing docs directory, move the doc files to 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., edit the project name and site description, install new extensions, …). 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.

Was this page helpful?

PREVIOUS
Toolchain
NEXT
Quickstart
  • Create an issue
  • Edit this page

On this page

  • Installation
    • Prerequisites
    • Step 1: Download the sample project
    • Step 2: Configure the theme
    • Step 3: Preview the site locally
    • Step 4: Deploy to GitHub Pages
ScyllaDB Sphinx Theme
  • 1.5
    • 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.4 to 1.5
    • Migrating from 1.3 to 1.4
    • 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