Installation¶

Prerequisites¶

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

• A Unix-based terminal. For Windows, use Windows Subsystem for Linux.

• Python 3.10 or 3.12.

• Poetry 1.8.1.

• Make.

• Git.

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. In the newly created docs folder, create a pyproject.toml file and copy the contents from the pyproject.toml template.

3. Create the file .github/dependabot.yml. Copy the contents from the dependabot.yml 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:

   cd docs
   make preview
   

   Tip

   For troubleshooting, refer to the preview command documentation.

3. Fix any warnings raised by Sphinx.

4. 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.