add: documentation

docs/20_discovery/documentation_build_and_deploy.md

@@ -0,0 +1,67 @@
+# 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.