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.

Sign up for GitHub

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

Jump to bottom

Unable to generate correct docs when one resource has same name as provider #419

Closed
1 task done
alexhung opened this issue Nov 13, 2024 · 5 comments · Fixed by #421
Closed
1 task done

Unable to generate correct docs when one resource has same name as provider #419

alexhung opened this issue Nov 13, 2024 · 5 comments · Fixed by #421
Labels
bug Something isn't working
Milestone
v0.20.1

Comments

@alexhung
Copy link

Terraform CLI and terraform-plugin-docs Versions

Terraform v1.9.5
on darwin_amd64
+ provider registry.terraform.io/jfrog/project v1.9.1
tfplugindocs Version dev // v0.20.0 in go.mod

Provider Code

terraform {
  required_providers {
    project = {
      source  = "jfrog/project"
      version = "1.9.0"
    }
  }
}

resource "project" "myproject" {
  key = "myproj"
  display_name = "My Project"
  description  = "My Project"
  admin_privileges {
    manage_members   = true
    manage_resources = true
    index_resources  = true
  }
  max_storage_in_gibibytes   = 10
  block_deployments_on_limit = false
  email_notification         = true
}

Expected Behavior

Able to generate correct doc files for all other resources when one resource has same name as the provider. In our case, the provider name is project and one of the resource name is also project.

Actual Behavior

When tfplugindocs generate is executed, all the resource docs are replaced by content from resource project doc.

Steps to Reproduce

  1. tfplugindocs generate. That's all required.

How much impact is this issue causing?

High

Logs

https://gist.github.com/alexhung/da5c294048169cef6cd73f026804bdb8

Additional Information

After generating doc, all resource doc files are modified even though none should be updated.

alexh@alexh-mac terraform-provider-project % git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   docs/resources/environment.md
	modified:   docs/resources/group.md
	modified:   docs/resources/project.md
	modified:   docs/resources/repository.md
	modified:   docs/resources/role.md
	modified:   docs/resources/share_repository.md
	modified:   docs/resources/share_repository_with_all.md
	modified:   docs/resources/user.md

no changes added to commit (use "git add" and/or "git commit -a")

Using --provider-name arg has no effect.

Code of Conduct

  • I agree to follow this project's Code of Conduct
@alexhung alexhung added the bug Something isn't working label Nov 13, 2024
@alexhung
Copy link
Author

When I run tfplugindocs validate --provider-name project, it fails with the following:

exporting schema from Terraform
compiling provider "project"
using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
running terraform init
getting provider schema
2024/11/13 14:08:43 [DEBUG] Found documentation files [docs/guides/repositories_in_project.md docs/index.md docs/resources/environment.md docs/resources/group.md docs/resources/project.md docs/resources/repository.md docs/resources/role.md docs/resources/share_repository.md docs/resources/share_repository_with_all.md docs/resources/user.md]
running mixed directories check
2024/11/13 14:08:43 [DEBUG] Found directory: docs/guides
2024/11/13 14:08:43 [DEBUG] Found directory: docs
2024/11/13 14:08:43 [DEBUG] Found directory: docs/resources
2024/11/13 14:08:43 [DEBUG] Found directory: docs/resources
2024/11/13 14:08:43 [DEBUG] Found directory: docs/resources
2024/11/13 14:08:43 [DEBUG] Found directory: docs/resources
2024/11/13 14:08:43 [DEBUG] Found directory: docs/resources
2024/11/13 14:08:43 [DEBUG] Found directory: docs/resources
2024/11/13 14:08:43 [DEBUG] Found directory: docs/resources
2024/11/13 14:08:43 [DEBUG] Found directory: docs/resources
running number of files check
2024/11/13 14:08:43 [TRACE] Found 1 documentation files in directory: docs/guides
2024/11/13 14:08:43 [TRACE] Found 8 documentation files in directory: docs/resources
2024/11/13 14:08:43 [DEBUG] Found 9 documentation files with limit of 2000
detected static docs directory, running checks
running invalid directories check on docs/guides
running file checks on docs/guides/repositories_in_project.md
2024/11/13 14:08:43 [DEBUG] Checking file: /Users/alexh/Projects/terraform-provider-project/docs/guides/repositories_in_project.md
2024/11/13 14:08:43 [DEBUG] File /Users/alexh/Projects/terraform-provider-project/docs/guides/repositories_in_project.md size: 2447 (limit: 500000)
running file checks on docs/index.md
2024/11/13 14:08:43 [DEBUG] Checking file: /Users/alexh/Projects/terraform-provider-project/docs/index.md
2024/11/13 14:08:43 [DEBUG] File /Users/alexh/Projects/terraform-provider-project/docs/index.md size: 9837 (limit: 500000)
running invalid directories check on docs/resources
running file checks on docs/resources/environment.md
2024/11/13 14:08:43 [DEBUG] Checking file: /Users/alexh/Projects/terraform-provider-project/docs/resources/environment.md
2024/11/13 14:08:43 [DEBUG] File /Users/alexh/Projects/terraform-provider-project/docs/resources/environment.md size: 1200 (limit: 500000)
running file checks on docs/resources/group.md
2024/11/13 14:08:43 [DEBUG] Checking file: /Users/alexh/Projects/terraform-provider-project/docs/resources/group.md
2024/11/13 14:08:43 [DEBUG] File /Users/alexh/Projects/terraform-provider-project/docs/resources/group.md size: 1441 (limit: 500000)
running file checks on docs/resources/project.md
2024/11/13 14:08:43 [DEBUG] Checking file: /Users/alexh/Projects/terraform-provider-project/docs/resources/project.md
2024/11/13 14:08:43 [DEBUG] File /Users/alexh/Projects/terraform-provider-project/docs/resources/project.md size: 7627 (limit: 500000)
running file checks on docs/resources/repository.md
2024/11/13 14:08:43 [DEBUG] Checking file: /Users/alexh/Projects/terraform-provider-project/docs/resources/repository.md
2024/11/13 14:08:43 [DEBUG] File /Users/alexh/Projects/terraform-provider-project/docs/resources/repository.md size: 1128 (limit: 500000)
running file checks on docs/resources/role.md
2024/11/13 14:08:43 [DEBUG] Checking file: /Users/alexh/Projects/terraform-provider-project/docs/resources/role.md
2024/11/13 14:08:43 [DEBUG] File /Users/alexh/Projects/terraform-provider-project/docs/resources/role.md size: 2556 (limit: 500000)
running file checks on docs/resources/share_repository.md
2024/11/13 14:08:43 [DEBUG] Checking file: /Users/alexh/Projects/terraform-provider-project/docs/resources/share_repository.md
2024/11/13 14:08:43 [DEBUG] File /Users/alexh/Projects/terraform-provider-project/docs/resources/share_repository.md size: 1609 (limit: 500000)
running file checks on docs/resources/share_repository_with_all.md
2024/11/13 14:08:43 [DEBUG] Checking file: /Users/alexh/Projects/terraform-provider-project/docs/resources/share_repository_with_all.md
2024/11/13 14:08:43 [DEBUG] File /Users/alexh/Projects/terraform-provider-project/docs/resources/share_repository_with_all.md size: 1494 (limit: 500000)
running file checks on docs/resources/user.md
2024/11/13 14:08:43 [DEBUG] Checking file: /Users/alexh/Projects/terraform-provider-project/docs/resources/user.md
2024/11/13 14:08:43 [DEBUG] File /Users/alexh/Projects/terraform-provider-project/docs/resources/user.md size: 1676 (limit: 500000)
running file mismatch check
2024/11/13 14:08:43 [DEBUG] Found file environment.md
2024/11/13 14:08:43 [DEBUG] Found file group.md
2024/11/13 14:08:43 [DEBUG] Found file project.md
2024/11/13 14:08:43 [DEBUG] Found extraneous file project.md
2024/11/13 14:08:43 [DEBUG] Found file repository.md
2024/11/13 14:08:43 [DEBUG] Found file role.md
2024/11/13 14:08:43 [DEBUG] Found file share_repository.md
2024/11/13 14:08:43 [DEBUG] Found file share_repository_with_all.md
2024/11/13 14:08:43 [DEBUG] Found file user.md
2024/11/13 14:08:43 [DEBUG] Found resource project
2024/11/13 14:08:43 [DEBUG] Missing file for resource project
2024/11/13 14:08:43 [DEBUG] Found resource project_environment
2024/11/13 14:08:43 [DEBUG] Found resource project_group
2024/11/13 14:08:43 [DEBUG] Found resource project_repository
2024/11/13 14:08:43 [DEBUG] Found resource project_role
2024/11/13 14:08:43 [DEBUG] Found resource project_share_repository
2024/11/13 14:08:43 [DEBUG] Found resource project_share_repository_with_all
2024/11/13 14:08:43 [DEBUG] Found resource project_user
Error executing command: validation errors found:
matching resource for documentation file (project.md) not found, file is extraneous or incorrectly named
missing documentation file for resource: project

@alexhung alexhung mentioned this issue Nov 13, 2024
Merged
@austinvalle austinvalle mentioned this issue Nov 18, 2024
Merged
@austinvalle
Copy link
Member

Hey there @alexhung 👋🏻 ,

Thanks for reporting the bug and sorry you're running into trouble. I fixed a couple bugs related to the issues you were running into over in #421, which if you'd like to test out, you can try out with:

go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@a50a29dee950846f1ac7e2249e2a2d666aae98e8

# This just happens to be where my $GOBIN is, replace this path with wherever yours is or install it differently if you'd like
/Users/austin.valle/go/bin/tfplugindocs generate
/Users/austin.valle/go/bin/tfplugindocs validate

I ran it on your repo over at https://github.com/jfrog/terraform-provider-project and there's a couple additional things to note:

  1. You may have been running into a problem with the https://github.com/jfrog/terraform-provider-project/blob/master/templates/debug.md file causing an error to be thrown, which the tfplugindocs tool is supposed to ignore those files in the destination location (/docs). You can actually just delete the templates/debug.md file and just maintain it in the docs/debug.md file if you'd like to avoid having to delete the entire docs folder before re-running.

    TLDR: Static files that exist in both /templates and /docs will not be copied over

  2. There are some minor differences running through the generator, but most notably is related to blocks, which don't have the information for Optional/Required blocks, and default to optional, see Required blocks in resources implemented with terraform-plugin-framework are listed as optional #363. You can template around this problem with a templates/resources/project.md.tmpl if you'd prefer.

@alexhung
Copy link
Author

Thanks @austinvalle for the quick fix!

I've tested in my provider and all seems to work well!

W.r.t.:

  1. This line in README "Copy all non-template files to the output website directory" implies static file in templates directory will be copied over to the doc directory. In reality, this triggers an error if the static file already exists, hence we delete the entire directory first.
  2. We are aware of this

@austinvalle
Copy link
Member

austinvalle commented Nov 18, 2024 •
edited
Loading

Okay cool! Thanks for that test and extra info, we'll look to get this patch merged and released in a v0.20.1 soon 👍🏻

@austinvalle austinvalle added this to the v0.20.1 milestone Nov 18, 2024
@austinvalle
Copy link
Member

This fix is available in the v0.20.1 release, which just went out 👍🏻 : https://github.com/hashicorp/terraform-plugin-docs/releases/tag/v0.20.1

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Dec 27, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
bug Something isn't working
Projects
None yet
Milestone
v0.20.1
2 participants
@alexhung @austinvalle