# Commands

Use the command-line interface to run the following commands.

#### NOTE
Make sure you meet the necessary prerequisites before running these commands. For details, see [Prerequisites](https://sphinx-theme.scylladb.com/master/getting-started/quickstart.md#prerequisites).

## Setup commands

### setupenv

Installs system dependencies required to build the docs, such as uv.

```console
make setupenv
```

### setup

Installs the required Python dependencies to build the documentation.

```console
make setup
```

#### NOTE
`make setup` is called automatically before running build commands.

### update

Updates Python dependencies to the latest version.

```console
make update
```

As a result, updates the `uv.lock` file.

## Build commands

<a id="make-preview"></a>

### preview

Builds a local instance of the docs site so you can view the rendering in a sandbox environment on your local browser.

To preview the docs:

1. Build the docs.
   > ```console
   > cd docs
   > make preview
   > ```
2. Open [http://127.0.0.1:5500/](http://127.0.0.1:5500/) with your preferred browser.

To increase verbosity, use the option `-v`:

> ```console
> make preview SPHINXOPTS=-v
> ```

To decrease verbosity, use the option `-Q`:

> ```console
> make preview SPHINXOPTS=-Q
> ```

#### Troubleshooting

##### Issue: pyproject.toml changed significantly since uv.lock was last generated

**Solution:**

1. Run the following command:
   > ```console
   > uv lock
   > ```
2. Run the make preview command again.

### multiversionpreview

Generates a local instance of the docs site with all [specified versions](https://sphinx-theme.scylladb.com/master/configuration/multiversion.md) available for navigation.
You can view the rendering in a sandbox environment on your local browser.

To preview multiple versions:

1. Build the docs.
   > ```console
   > cd docs
   > make multiversionpreview
   > ```
2. Open [http://0.0.0.0:5500/](http://0.0.0.0:5500/) with your preferred browser.

For further guidance on using the `multiversionpreview command`, see [Multiversion configuration](https://sphinx-theme.scylladb.com/master/configuration/multiversion.md).

### dirhtml

Generates the documentation in HTML format.

#### NOTE
The command `make dirhtml` is aimed to be used by GitHub Actions CI. While documenting new features, it is not advised to run `make dirhtml`, but `make preview` instead.

```console
cd docs
make multiversion
```

Docs are generated under the `docs/_build/dirhtml` directory.

### multiversion

Generates multiple versions of the docs with all [specified versions](https://sphinx-theme.scylladb.com/master/configuration/multiversion.md) available for navigation.

#### NOTE
The command `make multiversion` is aimed to be used by GitHub Actions CI. While documenting new features, it is not advised to run `make multiversion`, but `make preview` instead.

```console
cd docs
make multiversion
```

Docs are generated under the `docs/_build/dirhtml` directory.

### redirects

Generates HTML redirects from the `_utils/redirects.yaml` file.

#### NOTE
The command `make multiversion` is aimed to be used by GitHub Actions CI.

```console
cd docs
make multiversion
```

Redirects are generated under the `docs/_build/dirhtml` directory.

## Clean commands

### clean

Before making changes to the docs, it’s helpful to clear the previous build by deleting the contents of the `build` directory.
This ensures that the changes you make are reflected correctly.

```console
cd docs
make clean
```

## Test commands

### linkcheck

Checks the documentation site for broken links.

```console
cd docs
make dirhtml
make linkcheck
```