feat: migrate to tfplugindocs auto-generated documentation

[mkushakov]

Resolves #3241

Summary

Migrates documentation from the manually-maintained website/docs/ format to auto-generated documentation using terraform-plugin-docs (tfplugindocs).

Motivation

Currently, documentation is manually written in website/docs/ as .html.markdown files. This approach has several limitations:

• Schema changes don't automatically reflect in docs
• No validation that docs match the actual provider schema
• Inconsistent formatting across resource docs
• No extraction of example HCL code into testable files

The tfplugindocs tool is the standard approach used by most Terraform providers and provides:

• Template-based docs in templates/ that can reference schema descriptions via {{ .SchemaMarkdown }}
• Extracted HCL examples in examples/ that can be tested
• Auto-generation of docs/ output via make docs-generate
• Validation via make docs-validate

Changes

• tools.go (new): Adds terraform-plugin-docs as a tool dependency alongside existing misspell and golangci-lint
• GNUmakefile: Adds three new targets:
  • docs-generate — generates docs/ from templates/
  • docs-validate — validates generated docs
  • docs-migrate — one-time migration from website/docs/ to templates/ format
• templates/ (new): Contains .md.tmpl template files migrated from website/docs/
• examples/resources/, examples/data-sources/ (new): Extracted HCL code examples
• docs/ (new): Auto-generated output — replaces website/docs/
• website/docs/ (removed): Replaced by docs/
• go.mod/go.sum: Added terraform-plugin-docs dependency

Pre-existing fixes

The migration also fixed two pre-existing YAML frontmatter indentation issues in the OIDC subject claim customization template docs that caused validation failures.

Workflow

After this change, the documentation workflow becomes:

1. Edit templates in templates/ or update schema descriptions in Go source code
2. Run make docs-generate to regenerate docs/
3. Run make docs-validate to verify
4. Commit both templates/ changes and docs/ output

Templates can gradually be enhanced to use {{ .SchemaMarkdown }} for auto-generated schema documentation as schema descriptions are improved in the provider source code.

[github-actions]

👋 Hi! Thank you for this contribution! Just to let you know, our GitHub SDK team does a round of issue and PR reviews twice a week, every Monday and Friday! We have a process in place for prioritizing and responding to your input. Because you are a part of this community please feel free to comment, add to, or pick up any issues/PRs that are labeled with Status: Up for grabs. You & others like you are the reason all of this works! So thank you & happy coding! 🚀