Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Feature]: Increase usage of generation for provider docs #724

Open
ctreatma opened this issue Jul 10, 2024 · 0 comments
Open

[Feature]: Increase usage of generation for provider docs #724

ctreatma opened this issue Jul 10, 2024 · 0 comments
Labels
enhancement New feature or request

Comments

@ctreatma
Copy link
Contributor

Description

In v2 we adopted terraform-plugin-docs to enable generation of provider docs from provider code. In the initial migration we created templates from the existing docs to minimize the amount of change introduced in a single PR. This means that even though we use terraform-plugin-docs, we are still generally using it with hand-written, hard-coded templates that are simply copied from templates/ to docs/. This results in gaps between the attributes that are supported by a given resource or data source and the attributes that are mentioned in the docs.

To reduce this gap we should do one of the following for every custom template in templates/data-sources and templates/resources:

  • Remove the template and use the default template instead
  • Update the template to replace the schema documentation with a reference to {{ .SchemaMarkdown | trimspace }}

An example of the first approach can be seen in #719.

New or Affected Terraform Resources

This affects documentation for all resources and data sources

Potential Terraform Configuration

This is a documentation change and does not impact terraform configuration

@ctreatma ctreatma added the enhancement New feature or request label Jul 10, 2024
ctreatma added a commit that referenced this issue Aug 28, 2024
…nventional paths (#763)

In an effort to reduce the work required for #724, this renames the
existing resource & data source example directories so that they match
the [conventional
paths](https://github.com/hashicorp/terraform-plugin-docs?tab=readme-ov-file#conventional-paths)
for `tfplugindocs`.
ctreatma added a commit that referenced this issue Sep 9, 2024
This removes custom templates for some Fabric data sources and resources
to avoid missed docs changes due to hard-coded docs templates, which
partially addresses #724.

Changes made here are:  in cases where there is a single example file,
  1. rename that example to align with [conventional paths for examples in `tfplugindocs`](https://github.com/hashicorp/terraform-plugin-docs?tab=readme-ov-file#conventional-paths)
  2. remove the custom template so that the default template is used
  3. update the resource/data source description in code to match what was in the previous docs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant