hashicorp
`--rendered-provider-name` doesn't work
After upgrading from v0.9.0 to v0.13.0, the --rendered-provider-name seems to be ignored. E.g. when I run: tfplugindocs generate --rendered-provider-name=Restful --provider-name restful for my project https://github.com/magodo/terraform-provider-restful, there is no match in the docs folder for Restful:
terraform-provider-restful on action via 🐹 v1.18.5
💤 grep -r Restful docs
terraform-provider-restful on action via 🐹 v1.18.5
💢 grep -r restful docs
docs/index.md:page_title: "restful Provider"
docs/index.md: The restful provider provides resource and data source to interact with a platform that exposes a restful API.
docs/index.md:# restful Provider
docs/index.md:The restful provider provides resource and data source to interact with a platform that exposes a restful API.
docs/index.md:provider "restful" {
docs/resources/resource.md:page_title: "restful_resource Resource - restful"
docs/resources/resource.md: restful_resource manages a restful resource.
docs/resources/resource.md:# restful_resource (Resource)
docs/resources/resource.md:`restful_resource` manages a restful resource.
docs/resources/resource.md:resource "restful_resource" "rg" {
docs/resources/resource.md:terraform import restful_resource.example '{
docs/resources/operation.md:page_title: "restful_operation Resource - restful"
docs/resources/operation.md: restful_operation represents a one-time API call operation.
docs/resources/operation.md:# restful_operation (Resource)
docs/resources/operation.md:`restful_operation` represents a one-time API call operation.
docs/data-sources/resource.md:page_title: "restful_resource Data Source - restful"
docs/data-sources/resource.md: restful_resource data source can be used to retrieve the model of a restful resource by ID.
docs/data-sources/resource.md:# restful_resource (Data Source)
docs/data-sources/resource.md:`restful_resource` data source can be used to retrieve the model of a restful resource by ID.
docs/data-sources/resource.md:data "restful_resource" "test" {
if i understand this correctly, it is expected. you need to be using custom templates to make use of the {{ .RenderedProviderName }} - see https://github.com/cloudflare/terraform-provider-cloudflare/blob/master/templates/resources.md.tmpl#L2 for an example.
@jacobbednarz Thank you for the hint. After reviewing issue #173, I feel it is makes more sense to modify the default template to honor the rendered provider name, as is described in this option's description:
provider name, as generated in documentation (ex. page titles, ...)
I didn't see any reason why not do it.
rendered provider name isn't available by default -- it's only used if people supply it. if someone is supplying it, the assumption is that they are using a customised version of the generated docs. I don't agree this is a default that everyone will be using so it probably doesn't make sense for it to be there.
One argument is that the default template is almost useless without the support of rendered provider name.
E.g. back to my provider, it requires me to use --provider-name restful, otherwise, if I use --provider-name Restful, it failed to run terraform init with that:
💤 tfplugindocs generate --provider-name Restful
rendering website for provider "Restful" (as "Restful")
copying any existing content to tmp dir
exporting schema from Terraform
compiling provider "Restful"
using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
running terraform init
Error executing command: unable to generate website: configuration is invalid
Using --provider-name restful, the docs/index.md is like below:
---
# generated by https://github.com/hashicorp/terraform-plugin-docs
page_title: "restful Provider"
subcategory: ""
description: |-
The restful provider provides resource and data source to interact with a platform that exposes a restful API.
---
# restful Provider
The restful provider provides resource and data source to interact with a platform that exposes a restful API.
...snip
(the same for the resource/data source file)
As you can see that the advertise name of my provider is lowercased, I don't think any user will want that.
I'm sorry, I don't agree it's useless. For many (including the provider I maintain for a long time), it's all they need/want. I would say we could improve the UX here a little and do a if/else in the default template to check if the rendered name is provided, use it otherwise default back to what it is now. However, it's a bit of a fine line as once you start customising the output, you really want custom templates anyway.