tf_provider/docs/60_strategy/docs_generation_clickhouse_template.md

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.