# Production deployment

We use GitHub Pages and GitHub Actions to make the documentation publicly available.

On this page, you will learn:

- How to deploy to GitHub Pages.
- How to set up a custom domain.
- How to read build error messages.
- How to re-run a workflow.
- How to disable GitHub Pages.
- Where link checking is handled.

<a id="available-workflows"></a>

## Available workflows

The toolchain provides the following workflows under the directory `.github/workflows`:

| Filename              | Description                                                                                                                                                                                  |
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `docs-pages.yaml`     | Builds multi versioned docs every time the default branch (e.g. `master`)  receives an update. If the build completes successfully, the workflow publishes the HTML version to GitHub Pages. |
| `docs-pr.yaml`        | Builds the docs for pull requests and shows warnings and errors in the Actions summary and at the end of the build log.                                                                      |
| `docs-pr-report.yaml` | Reports warnings and errors in a pull request comment. Removes the comment when the build passes.                                                                                            |

#### CAUTION
If you modify these workflows in your repository, you will need to maintain the changes. So instead, we recommend you to open an issue in the [sphinx-scylladb-theme repository](https://github.com/scylladb/sphinx-scylladb-theme) so that all projects can benefit from the improvements you made.

## Installation

To install the workflows:

1. Copy the workflows named `docs-*.yaml` from [.github/workflows](https://github.com/scylladb/sphinx-scylladb-theme/blob/master/.github/workflows) to your project. The project’s directory structure should look like the following:
   > ```console
   > project-name/
   >   ├── .github/
   >   |   ├── workflows/
   >   |   |   ├── docs-pages.yaml
   >   |   |   ├── docs-pr.yaml
   >   |   |   ├── docs-pr-report.yaml
   > ```
2. If the default branch is not `master` or the docs are not located under the `docs` folder, modify the workflows to align with the project configuration. For example:
   > ```default
   > on:
   > push:
   >     branches:
   >     - master # edit this line
   >     paths:
   >     - "docs/**" # edit this line
   > ```
3. In the repository’s **Settings**, navigate to the **Pages** section and select **GitHub Actions** as the deployment source.
   > ![image](deployment/images/pages-configuration.png)
4. Commit and push the changes to your GitHub repository. Make sure to push these changes to the default branch.

Once you push the [workflows](#available-workflows) to the remote repository default branch, GitHub might take a couple of minutes to build and publish the site.

#### TIP
To monitor the progress of the build, look for the **Actions** tab below your repository name on GitHub.

If everything goes well, you will see the docs published under `https://scylladb.github.io/<repository-slug>`.

## Setting up a custom domain

#### NOTE
Setting up a custom domain requieres access to scylladb.com DNS configuration. Contact us in Slack `#scylla-docs` channel to set this configuration for you.

Follow the following steps to set up a custom domain:

1. In the domain’s DNS configuration, create a new CNAME record that points `<custom-sudomain>.scylladb.com` to `scylladb.github.io`.
2. Change `html_baseurl` setting in `conf.py` for the desired sub-domain name. For instance, we will use `sphinx-theme.scylladb.com`.
3. Commit and push the changes to your GitHub repository. Make sure to push these changes to the default branch.
4. In the repository’s **Settings**, navigate to the **Pages** section and make sure the custom domain name is set under **Custom domain** and **Enforce HTTPS** is enabled.

> ![image](deployment/images/pages-custom-domain.png)
1. Verify the domain name to restrict its usage only on ScyllaDB organization repositories. To do so, follow the steps in [Verifying your domain with GitHub](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages#verifying-a-domain-for-your-organization-site).
2. Once the DNS changes propagate (<24 h), the docs will be accessible from the custom domain name.

<a id="docs-build-reports"></a>

## Reading error messages

Docs builds can fail because of documentation errors or warnings.

`make test` uses Sphinx’s `-W` option, which treats warnings as build failures.

For pull requests, the **Docs / Build PR** comment lists warnings and errors and links to the full build log.
You can also find these messages in the Actions summary and at the end of the build log.

Once the build passes, the comment is removed. Successful builds do not create comments.

To view the full build output:

1. Hover the <i class="inline-icon icon-cancel" aria-hidden="true"></i> that you will see next to the commit message, and click on **Details**.
   > ![image](deployment/images/build-error.png)
2. Search for “warning” and “error” in the box you will find at the top right of the screen.
   > ![image](deployment/images/build-log.png)

You should see the error messages highlighted.

## Publishing the docs manually

If you need to manually trigger a documentation build and publish the latest changes, follow the steps below. This might be necessary if automatic triggers fail.

To manually rerun the last build, follow these steps:

1. Navigate to your repository’s **Actions** tab on GitHub.
2. In the list of workflows, locate and select the `docs-pages.yaml` workflow.
3. On the workflow’s page, click the **Run workflow** button. For more details, see [Manually running a workflow](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow).
4. **IMPORTANT:** When prompted, ensure you select the default branch (usually master or main). This ensures the workflow runs using the latest version of the configuration file, which contains information about which branches to build.
5. Confirm the action and wait for the workflow to complete.

## Disabling GitHub Pages

To disable the docs deployment temporarily:

1. Delete the [workflows](#available-workflows) from `.github/workflows`.
2. Disable GitHub Pages from the repository settings. For more information, see  [Unpublishing a GitHub Pages Site](https://help.github.com/en/github/working-with-github-pages/unpublishing-a-github-pages-site#unpublishing-a-project-site).

<a id="link-checking"></a>

## Link checking

Link checking is centralized in the [scylladb/scylladb-docs-homepage](https://github.com/scylladb/scylladb-docs-homepage) repository and maintained by the Technical Writing team. Individual project repositories no longer need to run their own link-check workflow.

The centralized workflow:

* Runs every Monday at 08:00 UTC, and can be triggered manually.
* Crawls each documentation site listed in [scripts/link-check/sites.yml](https://github.com/scylladb/scylladb-docs-homepage/blob/main/scripts/link-check/sites.yml) in parallel.
* Opens a GitHub issue in `scylladb-docs-homepage` for every site that has newly broken links, labelled `link-check` and `link-check:<slug>`.
* Skips links already tracked in another open issue for the same site, so issues do not duplicate findings.

To request a change (add or remove a site, exclude a URL, run a one-off check for a specific site), open an issue or pull request in [scylladb-docs-homepage](https://github.com/scylladb/scylladb-docs-homepage). See [scripts/link-check/README.md](https://github.com/scylladb/scylladb-docs-homepage/blob/main/scripts/link-check/README.md) for the full reference.