docs: generate docs from provider schema

[jooola]

This PR is based on top of #1046.

Generating the docs from the schema will give us an additional way of reviewing a provider's arguments, if they are read-only, arguments or attributes.

This also changes the way we refactor resources/data-sources to the plugin framework, the docs should not be moved to a markdown file, but generated from the code instead.

[codecov]

Codecov Report

Attention: Patch coverage is 96.25668% with 7 lines in your changes missing coverage. Please review.

Project coverage is 30.60%. Comparing base (45a3fb8) to head (288901f).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/deprecation/deprecation_plugin.go	50.00%	7 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #1032       +/-   ##
===========================================
- Coverage   66.28%   30.60%   -35.68%     
===========================================
  Files          66       66               
  Lines        9868     9942       +74     
===========================================
- Hits         6541     3043     -3498     
- Misses       2612     6859     +4247     
+ Partials      715       40      -675     

Flag	Coverage Δ
e2e	?
unit	30.60% <96.25%> (+0.51%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[jooola]

I am not sure what we should do with the old documentation that is now duplicate. I could copy the generated docs to the old files.

[apricote]

Registry docs

The Hashicorp & OpenTofu Registry display our docs, how do they react if we store part of the docs in docs/ and others in website/?

SDK v2

As far as I could tell you only updated the docs for resources/datasources that were already moved to plugin framework. Is there some technical limitation why you did not migrate SDKv2 resources?

[jooola]

Registry

Open tofu seem to support the new directory: https://search.opentofu.org/docs/providers/docs#documentation-structure and the old one, as we already have some docs there: https://search.opentofu.org/provider/opentofu/hcloud/latest/docs/datasources/firewall But I'm not sure if they can coexist.

Terraform doesn't document if both website and docs can coexist: https://developer.hashicorp.com/terraform/registry/providers/docs#migrating-legacy-providers-docs

According to the plugin docs tool, the website should be removed once the docs has been created: https://github.com/hashicorp/terraform-plugin-docs#migrate-subcommand

The legacy website/ directory will be removed after migration to avoid Terraform Registry ingress issues.

SDKv2

I thought the terraform plugin docs tool only support the plugin framework, but you are correct, we could migrate the SDKv2 providers to use the docs generation.

I am just wondering if this makes sense to do for the SDKv2, or if we prefer to migrate one resource after the other? Doing it in one shot will definitely help for the consistency, but I'm a not sure if I want to copy all those strings twice (docs generation and plugin framework migration).

Maybe we can replace the existing website files with the generated files for now, and do a big move once we are done with the plugin migration?

I'll think about what is best.

[jooola]

I thought about this a bit more, and we should migrate the whole website once. And gradually improve each module by replacing the existing static docs with the auto generated templates from the code (provider schema).

So this PR is missing the foundation on top of which it can happen.