# Documentation Build and Deployment Process

## Overview

This document describes the process of building and deploying the Terraform Provider documentation for the Nubes Registry. The system uses `mkdocs` with the `material` theme for static site generation and S3 for storage. The Registry Server serves these files directly from the S3 bucket.

## Architecture

1.  **Source**: Documentation source files are in `docs/` and configuration in `mkdocs.yml`.
2.  **Build**: The static HTML site is built using `mkdocs`.
    *   *Note*: Since `mkdocs` is not installed securely in the shell environment, we use the Docker image `squidfunk/mkdocs-material`.
3.  **Storage**: The built site is uploaded to an S3 bucket named `terraform-registry`.
4.  **Serving**: The Registry Server (`registry-server-build/`) reads files from `docs/{namespace}/{name}/{version}/` keys in the bucket and serves them via HTTP.

## Requirements

*   Docker (for building the docs safely)
*   `mc` (S3 client) configured with an alias (e.g., `nubes_s3`) pointing to the production S3 endpoint.
*   Access keys for the S3 bucket.

## Step-by-Step Process

### 1. Build the Documentation

Run the build using Docker to generate the `site/` directory:

```bash
docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build
```

This mounts the current directory to `/docs` in the container and runs `mkdocs build`. The output is placed in the local `site/` directory.

### 2. Deployment Script (`scripts/publish-docs.sh`)

We use a helper script to normalize the upload process. The script has been updated to point to the correct bucket path.

**Usage:**
```bash
./scripts/publish-docs.sh <site-dir> <registry-host> <namespace> <name> <version>
```

**Parameters:**
*   `site-dir`: Path to the built site (usually `site`).
*   `registry-host`: The host alias or endpoint (e.g., `s3.msk-1.ngcloud.ru` or internal logic, but effectively acts as part of the path structure in some versions, currently simplified to upload to `docs/...`).
*   `namespace`: Provider namespace (e.g., `nubes`).
*   `name`: Provider name (e.g., `nubes`).
*   `version`: Semver version (e.g., `1.0.0`).

### 3. Manual Deployment Command

If running manually without the script, use `mc` to mirror the `site/` folder to the target S3 path:

```bash
# Example for version 1.0.0
mc cp --recursive site/ nubes_s3/terraform-registry/docs/nubes/nubes/1.0.0/
```

## Troubleshooting

*   **Missing Dependencies**: If `mkdocs` is not found, always prefer the Docker command above.
*   **Path Errors**: Ensure the S3 path matches `docs/<namespace>/<name>/<version>/`. The registry server expects this exact structure to map URL paths to S3 keys.
*   **Bucket Access**: Verify `mc ls nubes_s3/terraform-registry` works before attempting upload.

## Recent Changes (Jan 2026)

*   Fixed `scripts/publish-docs.sh` to target the `terraform-registry` bucket instead of `terraform-providers`.
*   Standardized the S3 path structure to remove `REGISTRY_HOST` from the directory tree, aligning with `registry-server-build/docs.go` logic.