No Schema Discovery when using Resource/Data-Source specific templates

elXaptation commented 2 years ago

Not sure if I have the wrong expectation or if something is broken with resource and data-source templates. The template line:

{{ .SchemaMarkdown | trimspace }} seems to break/not-function when I create these specific templates.

I have my internal/provider/resource_plugin.go and internal/provider/datasource_plugin.go files defined. I create templates:

templates/resource/plugin.md.tmpl and templates/data-sources/plugin.md.tmpl

run tfplugindocs in the root of my plugin repo and get an error:

Error executing command: unable to generate website: unable to render template "data-sources/plugin.md.tmpl": unable to execute template: template: docTemplate:11:21: executing "docTemplate" at <trimspace>: invalid value; expected string

This trimspace error is related to .SchemaMarkdown return "". Seems that .SchemaMarkdown can't find the

func resourcePlugin() *schema.Resource in resource_plugin.go (nor datasource_plugin.go).

If I don't create specific templates, tfplugindocs runs to completion and all the files are generated. Although without the custom content I'd like to include.

I'm expecting my specific templates to allow me to create custom md-headers and other content, while .SchemaMarkdown does it's thing.

Creating the specific template index.md.tmpl works as I expect.

Is this how templates/resource/plugin.md.tmpl and templates/datasources/plugin.md.tmpl are suposed to work?

Thank you.

jacobbednarz commented 2 years ago

this isn't just you; i'm also hitting this. somewhere between 0.5.1 and 0.9.0 something is now causing this individual resource templates to fail. i'm still trying to put together a test case to bisect.

jacobbednarz commented 2 years ago

looks like there is more nuance here than "doesn't work with 0.9.0" as https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy works with individual resource templates and is using 0.9.0. still digging...

jacobbednarz commented 2 years ago

narrowing this down further; tfplugindocs by itself works but tfplugindocs generate does not.

jacobbednarz commented 2 years ago

here are my findings so far.

to have individual templates rendered you need to:

use tfplugindocs directly, not tfplugindocs generate
have the template filename wthout the provider name prefixed (i.e. access_application.md.tmpl not cloudflare_access_application.md.tmpl like when you want to copy the file verbatim.

will need to dig into why this is and doesn't meet the same criteria as the tfplugindocs generate command as it also means you cannot pass in configuration flags with the default commands.

elXaptation commented 2 years ago

Oh. Interesting. Thanks for sharing. Still wonder if this is intended or not. Seems as to not be intended.

On Sun, Jun 12, 2022, 17:28 Jacob Bednarz @.***> wrote:

here are my findings so far.

to have individual templates rendered you need to:

use tfplugindocs directly, not tfplugindocs generate

have the template filename wthout the provider name prefixed (i.e. access_application.md.tmpl not cloudflare_access_application.md.tmpl like when you want to copy the file verbatim.

will need to dig into why this is and doesn't meet the same criteria as the tfplugindocs generate command as it also means you cannot pass in configuration flags with the default commands.

— Reply to this email directly, view it on GitHub https://github.com/hashicorp/terraform-plugin-docs/issues/139#issuecomment-1153334364, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEXNTRWZM7XF35WKAOWBB7DVOZ6C5ANCNFSM5WYIHR3A . You are receiving this because you authored the thread.Message ID: @.***>

jacobbednarz commented 2 years ago

I wouldn't suspect it is intended. Now that I've found where it works, I can have a look into why this isn't working.

jacobbednarz commented 2 years ago

found the cause of this and addressed in #148; blame past Jacob. feel free to pull that locally and give it a whirl.

elXaptation commented 2 years ago

Hey Guys,

Seems something still a miss here. Related to naming, I believe 0.10.0 is unable to find some resource it created itself. This provider doesn't have any actual template defined.. so tfplugindocs creates all the templates, then complains it can't find them.. Any thoughts?

elXaptation:~/terraform-provider-plat$ ../tfplugindocs_0100 
rendering website for provider "terraform-provider-plat" (as "terraform-provider-plat")
copying any existing content to tmp dir
exporting schema from Terraform
compiling provider "plat"
using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
running terraform init
getting provider schema
rendering missing docs
generating missing resource content
generating template for "cloud_router_bgp_session"
generating template for "cloud_services_aws_create_backbone_dedicated_cr"
generating template for "cloud_services_aws_hosted_connection"
generating template for "cloud_services_aws_req_hosted_conn"
generating template for "interface"
generating template for "aws_cloud_router_connection"
generating template for "cloud_router"
generating template for "cloud_router_bgp_prefixes"
generating template for "cloud_services_aws_dedicated"
generating template for "cloud_services_aws_hosted_marketplace"
generating template for "cloud_services_aws_provision_requested_mkt_conn"
generating missing data source content
generating template for "cloud_services_aws_connection_info"
generating template for "cloud_services_aws_dedicated_conn"
generating template for "locations"
generating template for "aws_cloud_router_connection"
generating template for "billing"
generating template for "cloud_router"
generating template for "cloud_router_bgp_prefixes"
generating template for "cloud_router_bgp_session"
generating missing provider content
provider "terraform-provider-plat" template exists, skipping
rendering static website
cleaning rendered website dir
rendering templated website to static markdown
rendering "data-sources/aws_cloud_router_connection.md.tmpl"
Error executing command: unable to generate website: unable to find resource for provider (plat) and template (aws_cloud_router_connection.md.tmpl)

I verified the md.tmpl files where created in the tmp directory. Any suggestions on how to trouble shoot this further?

jacobbednarz commented 2 years ago

can you link me to your repository? I suspect the filename is incorrect and not matching what the schema expects for this resource as the others work just fine.

elXaptation commented 2 years ago

Hi @jacobbednarz , thanks for the responses.

Unfortunately I can't share a link to the repo. Not public yet, and its not mine to share. Should go public once I figure out how to finish the docs.

However this is the directory/file structure that exists after running tfplugindocs version 0.10.0

You'll find I have a Directory: tmpls-notworking, where I'm keeping my intended, manually created, tmpls that were not working properly with schema discovery in 0.9.0.

I was thinking the error is coming from not being able to find the template tfplugindocs created. But perhaps I'm thinking about the wrong file names aligning.

elXaptation:~/terraform-provider-plat$ ../tfplugindocs_0100 generate
rendering website for provider "terraform-provider-plat" (as "terraform-provider-plat")
copying any existing content to tmp dir
exporting schema from Terraform
compiling provider "plat"
using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
running terraform init
getting provider schema
rendering missing docs
generating missing resource content
generating template for "cloud_services_aws_hosted_marketplace"
generating template for "interface"
generating template for "cloud_router_bgp_prefixes"
generating template for "cloud_router_bgp_session"
generating template for "cloud_services_aws_dedicated"
generating template for "cloud_services_aws_hosted_connection"
generating template for "cloud_services_aws_req_hosted_conn"
generating template for "aws_cloud_router_connection"
generating template for "cloud_router"
generating template for "cloud_services_aws_create_backbone_dedicated_cr"
generating template for "cloud_services_aws_provision_requested_mkt_conn"
generating missing data source content
generating template for "aws_services_hosted_requested_mkt_conn"
generating template for "billing"
generating template for "cloud_router_bgp_prefixes"
generating template for "cloud_router_bgp_session"
generating template for "cloud_services_aws_connection_info"
generating template for "cloud_services_aws_dedicated_conn"
generating template for "aws_cloud_router_connection"
generating template for "locations"
generating template for "cloud_router"
generating missing provider content
provider "terraform-provider-plat" template exists, skipping
rendering static website
cleaning rendered website dir
rendering templated website to static markdown
rendering "data-sources/aws_cloud_router_connection.md.tmpl"
Error executing command: unable to generate website: unable to find resource for provider (plat) and template (aws_cloud_router_connection.md.tmpl)

elXaptation:~/terraform-provider-plat$ tree .
.
|-- LICENSE
|-- Makefile
|-- README.md
|-- docs
|   `-- data-sources
|       `-- aws_cloud_router_connection.md
|-- examples
|   |-- cloud_router_aws_conn.tf
|   |-- data-sources
|   |   |-- aws_cloud_router_connection
|   |   |   `-- data-source.tf
|   |   |-- billing
|   |   |   `-- data-source.tf
|   |   |-- cloud_router
|   |   |   `-- data-source.tf
|   |   |-- cloud_router_bgp_prefixes
|   |   |   `-- data-source.tf
|   |   |-- cloud_router_bgp_session
|   |   |   `-- data-source.tf
|   |   |-- cloud_services_aws_connection_info
|   |   |   `-- data-source.tf
|   |   |-- cloud_services_aws_dedicated_conn
|   |   |   `-- data-source.tf
|   |   `-- locations
|   |       `-- data-source.tf
|   |-- env_vars_source.sh
|   |-- env_vars_source_private.sh
|   |-- main_aws.tf
|   |-- provider
|   |   `-- provider.tf
|   |-- resources
|   |   |-- aws_cloud_router_connection
|   |   |   `-- resource.tf
|   |   |-- cloud_router
|   |   |   `-- resource.tf
|   |   |-- cloud_router_bgp_prefixes
|   |   |   `-- resource.tf
|   |   |-- cloud_router_bgp_session
|   |   |   `-- resource.tf
|   |   |-- cloud_services_aws_create_backbone_dedicated_cr
|   |   |   `-- resource.tf
|   |   |-- cloud_services_aws_dedicated
|   |   |   `-- resource.tf
|   |   |-- cloud_services_aws_hosted_connections
|   |   |   `-- resource.tf
|   |   |-- cloud_services_aws_hosted_marketplace
|   |   |   `-- resource.tf
|   |   |-- cloud_services_aws_provision_requested_mkt_conn
|   |   |   `-- resource.tf
|   |   |-- cloud_services_aws_req_hosted_conn
|   |   |   `-- resource.tf
|   |   `-- interface
|   |       `-- resource.tf
|   `-- variables.tf
|-- examples_test
|   |-- aws_cloud_router.tf
|   |-- aws_cloud_router_conn_bgp.tf
|   |-- aws_cloud_router_connection.tf
|   |-- aws_dedicated_conn.tf
|   |-- aws_hosted_mkt.tf
|   |-- aws_provision_requested_mkt.tf
|   |-- billings.tf
|   |-- interface.tf
|   `-- locations.tf
|-- go.mod
|-- go.sum
|-- internal
|   |-- plat
|   |   |-- aws_backbone.go
|   |   |-- aws_backbone_test.go
|   |   |-- bgp_session.go
|   |   |-- bgp_session_test.go
|   |   |-- billing.go
|   |   |-- client.go
|   |   |-- cloud_router.go
|   |   |-- cloud_router_connection.go
|   |   |-- cloud_router_connection_test.go
|   |   |-- cloud_router_test.go
|   |   |-- cloud_service_aws.go
|   |   |-- interfaces.go
|   |   |-- locations.go
|   |   `-- service_status_check.go
|   `-- provider
|       |-- datasource_aws_dedicated_conn.go
|       |-- datasource_aws_hosted_service.go
|       |-- datasource_bgp_prefixes.go
|       |-- datasource_bgp_session.go
|       |-- datasource_billing.go
|       |-- datasource_cloud_conn_aws.go
|       |-- datasource_cloud_router.go
|       |-- datasource_cloud_service_aws.go
|       |-- datasource_locations.go
|       |-- provider.go
|       |-- resource_aws_backbone.go
|       |-- resource_aws_hosted_mkt.go
|       |-- resource_aws_hosted_mkt_conn.go
|       |-- resource_aws_provision_mkt.go
|       |-- resource_aws_request_dedicated_conn.go
|       |-- resource_aws_request_hosted_conn.go
|       |-- resource_bgp_refixes.go
|       |-- resource_bgp_session.go
|       |-- resource_cloud_router.go
|       |-- resource_interfaces.go
|       `-- resource_router_connection.go
|-- main.go
|-- main.tf
|-- templates
|   |-- data-sources
|   |-- index.md.tmpl
|   `-- resources
|-- terraform-registry-manifest.json
|-- tmpls-notworking
|   |-- data-sources
|   |   |-- aws_cloud_router_connection.md.tmpl
|   |   |-- billing.md.tmpl
|   |   |-- cloud_router.md.tmpl
|   |   |-- cloud_router_bgp_prefixes.md.tmpl
|   |   |-- cloud_router_bgp_session.md.tmpl
|   |   |-- cloud_services_aws_connection_info.md.tmpl
|   |   |-- cloud_services_aws_dedicated_conn.md.tmpl
|   |   `-- locations.md.tmpl
|   `-- resources
|       |-- aws_cloud_router_connection.md.tmpl
|       |-- cloud_router.md.tmpl
|       |-- cloud_router_bgp_prefixes.md.tmpl
|       |-- cloud_router_bgp_session.md.tmpl
|       |-- cloud_services_aws_create_backbone_dedicated_cr.md.tmpl
|       |-- cloud_services_aws_dedicated.md.tmpl
|       |-- cloud_services_aws_hosted_connection.md.tmpl
|       |-- cloud_services_aws_hosted_marketplace.md.tmpl
|       |-- cloud_services_aws_provision_requested_mkt_conn.md.tmpl
|       |-- cloud_services_aws_req_hosted_conn.md.tmpl
|       `-- interface.md.tmpl
`-- tools
    `-- tools.go

elXaptation commented 2 years ago

This issue is resolved in 0.10.1 #150

github-actions[bot] commented 4 months ago

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.

hashicorp / terraform-plugin-docs

No Schema Discovery when using Resource/Data-Source specific templates #139