feat: use tfplugindocs and update schema for auto doc generation

[matt-FFFFFF]

Problem statement

Manually crafting documentation is no longer feasible as the provider gets more complex. The risk of misalignments between schema and docs is high.

Summary

Now that the provider uses the plugin framework, we can generate documentation automatically based on the schema.

URI Change

This change will modify the name of the generated docs files in line with Hashicorp's best practice - there is no way to avoid this. The provider prefix is removed, so the URI will change:

Before: /providers/Azure/azapi/latest/docs/resources/azapi_update_resource After: /providers/Azure/azapi/latest/docs/resources/update_resource

This will mean that search indexes will take a while to update. However, we have to make this change sooner or later and I believe that this the benefits of auto doc generation outweigh the issues caused by a brief period of search crawler updates.

To do this we start using tfplugin docs (as recommended by Hashicorp for all these projects).

Details

• Modify main.go to include go generate comments
• Update GNUMakefile to include make docs command and remove legacy website targets
• Move guide content to templates to be copied by tfplugindocs tool
• Update resource schema to add MarkdownDescription fields
• Create templates for resources and data sources
• Implemented docstrings package to standardize messaging and simplify markdown formatting for common schema attributes
• Added custom template for data_plane_resource to add table.
• go mod vendor update
• Modify test job to include doc gen checks

[matt-FFFFFF]

@ms-henglu please can I get your thoughts?

[ms-henglu]

Thanks @matt-FFFFFF ! This looks great, and makes it much easier to maintain the docs. I'll check this PR later. Thanks!

[stemaMSFT]

Another little minor detail here; @ms-henglu correct me if I'm wrong but I think tons of examples right now set schema_validation_enabled = false and also response_export_values = ["*"]. Is there a way for us to improve that?

[ms-henglu]

Another little minor detail here; @ms-henglu correct me if I'm wrong but I think tons of examples right now set schema_validation_enabled = false and also response_export_values = ["*"]. Is there a way for us to improve that?

Thanks @stemaMSFT , yes, I'll open another PR to improve it.

[matt-FFFFFF]

@ms-henglu I have merged in the latest changes to main - WDYT about using for v2?

[matt-FFFFFF]

All changes addressed, also updated README to guide on how to generate docs