# 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:

- A Unix-based terminal. For Windows, use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install).
- [Python 3.11 or later](https://www.python.org/downloads/).
- [uv](https://docs.astral.sh/uv/getting-started/installation/).
- Make
- [Git](https://git-scm.com/).

## Step 1: Download the sample project

1. Copy the `docs` directory from the repository [scylladb/sphinx-scylladb-theme](https://github.com/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:
   ```console
   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](https://github.com/scylladb/sphinx-scylladb-theme/blob/master/docs/_utils/pyproject_template.toml).
3. Create the file `.github/dependabot.yml`. Copy the contents from the [dependabot.yml template](https://github.com/scylladb/sphinx-scylladb-theme/blob/master/docs/_utils/dependabot_template.yml).

## 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](https://sphinx-theme.scylladb.com/master/configuration/index.md).
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:
   > ```console
   > cd docs
   > make preview
   > ```
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](https://sphinx-theme.scylladb.com/master/deployment/production.md).