# 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](https://www.python.org/downloads/) or later.
- [Poetry 1.12](https://python-poetry.org/docs/master/) or later.

## 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. Create the file `docs/pyproject.toml` under the new `docs` folder. Copy the contents from the [pyproject.toml template](https://github.com/scylladb/sphinx-scylladb-theme/blob/master/docs/_utils/pyproject_template.toml).

## 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/branch-1.5/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. 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](https://sphinx-theme.scylladb.com/branch-1.5/deployment/production.md).