# Commands

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

## Prerequisites

To run the following commands, 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.7](https://www.python.org/downloads/) or later.
- [Poetry #.12](https://python-poetry.org/docs/master/) or later.
- [Make](https://www.gnu.org/software/make/).
- [Git](https://git-scm.com/).

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

## Preview current branch

The preview command 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
> ```

## Preview multiversion

The multiversionpreview command generates a local instance of the docs site with all [specified versions](https://sphinx-theme.scylladb.com/branch-1.7/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/branch-1.7/configuration/multiversion.md).

## Build HTML for multiple versions

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

The previous command generates HTML docs under the `docs/_build/dirhtml` directory.

## Clean all builds

The `make preview` operation creates content in the `_build` directory. When making changes to the docs, it is helpful to delete the contents of this directory before running `make preview`.

```console
cd docs
make clean
```

## Check for broken links

Check for broken links on the documentation site.

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