# Docs Generation Strategy: ClickHouse Template

## Purpose
This document captures the current documentation generation logic based on the ClickHouse template. It is a living reference and should be updated when the generator logic changes or issues are found.

## Scope
- Applies to all resources generated from API-derived YAML specs in:
  - `universal_rebuild/resources_yaml/*.yaml`
- Output target:
  - `docs/30_registry/resources/`
- ClickHouse is the reference template and is excluded from automatic generation by default.

## Current Generator
- Go generator:
  - `universal_rebuild/tools/docs_template_gen/main.go`
- Runner script:
  - `devops/02_generate_resources_and_docs_template.sh`

## Input Sources
- Primary source of truth: API YAML specs
  - `universal_rebuild/resources_yaml/*.yaml`
- Service ordering:
  - `devops/services_list.txt`

## Output Structure (per resource)
For each resource `name`, the generator writes:
- `name.md` (Manual)
- `name_params_create.md`
- `name_params_modify.md`
- `name_outputs.md`
- `name_ops.md`
- `name_example.md`
- `name_params.md` (landing)

Each page uses a fixed nav row:
`Manual | Create params | Modify params | Output params | Operations | Example`

## Template Notes
- Manual page uses `service_man` content from YAML.
- Example page builds a copy-ready manifest with required params first, then default params.
- Create params are split into:
  - Required params (no Default column)
  - Params with defaults (Default column kept)
- Modify params table has no Required or Default columns.
- Output params list is derived from `outputs.params`.
- Operations page lists actions with links to Create/Modify pages and subresources where present.
- Lifecycle defaults are rendered as a small note at the end of Create params if present in YAML.

## Snapshot + Validation Process
Before running the generator, take a snapshot of the current ClickHouse docs:
- Location: `docs/30_registry/resources/_snapshot_clickhouse_YYYYMMDD/`
- Content: copy all `clickhouse*.md`

After generation, compare the new outputs to the snapshot to validate:
- Nav row consistency
- Table structure and column rules
- Lifecycle note format and line breaks
- Example formatting and default params separation

## Known Exclusions
- ClickHouse is excluded by default to preserve manual refinements.
- To include ClickHouse for testing, remove it from the generator exclude list.

## Update Policy
- When generator logic changes, update this document.
- Record any issues found during comparison and how they were resolved.