Generated documentation with same-named nested blocks ends up with a single hash tag link

anilkumarmyla commented 4 months ago

Community Note

Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request.
Please do not leave +1 or me too comments, they generate extra noise for issue followers and do not help prioritize the request.
If you are interested in working on this issue or have submitted a pull request, please leave a comment.
If an issue is assigned to a user, that user is claiming responsibility for the issue.
Customers working with a Google Technical Account Manager or Customer Engineer can ask them to reach out internally to expedite investigation and resolution of this issue.

Terraform Version & Provider Version(s)

latest versions Terraform vX.X.X on

provider registry.terraform.io/hashicorp/google vX.X.X
provider registry.terraform.io/hashicorp/google-beta vX.X.X

Affected Resource(s)

google_access_context_manager_service_perimeter

Terraform Configuration

Debug Output

No response

Expected Behavior

On this page https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/access_context_manager_service_perimeter#nested_egress_from

From egress_policies > egress_from > sources, if you click 'sources' or its structure hyperlink it directs to ingress_from sources which is slighly different from egress_from sources. This hyperlink should be fixed.

Actual Behavior

No response

Steps to reproduce

terraform apply

Important Factoids

No response

References

No response

ggtisc commented 3 months ago

Hi @anilkumarmyla

It looks like it's fixed, please try again. If you continue having issues, do basic troubleshooting like restarting your browser, try with another browser, change your screen-browser-configurattion, clean cache, cookies, etc.

anilkumarmyla commented 3 months ago

It looks like it's fixed, please try again.

Nope, is there a commit that can be referenced for this fix?

If you continue having issues, do basic troubleshooting like restarting your browser, try with another browser, change your screen-browser-configurattion, clean cache, cookies, etc.

Come on now, this is not a browser issue

roaks3 commented 3 months ago

Following up with a look at the code, this is a systemic issue that has been present for a long time (since https://github.com/GoogleCloudPlatform/magic-modules/pull/5192). For another example, see the encryption_config link under https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/alloydb_cluster#nested_continuous_backup_config.

Basically, our logic for generated docs does not consider the parent of the field, so when there are duplicate field names anywhere within the schema, this can occur.

An ideal solution would probably include the parent field(s) in the anchor, but I think that solution would break existing links that are being used. To preserve current links while fixing the issue, we may need to somehow modify the anchors used by all but the first occurrence (eg. nested_source, nested_sources2, etc.).

SarahFrench commented 3 weeks ago

The Registry team just pushed a fix for this type of problem that makes anchor links unique and able to handle fields with the same name nested in different locations. However, this only affects anchors that the Registry adds itself when rendering the documentation.

For example:

This doesn't fully solve the problem because there are also anchor links in the Google provider documentation that we control by how we generate the markdown for the provider documentation. We template documentation to have links to sections describing blocks ("Structure is documented below.") and those links use anchors named like nested_sources. If there are multiple blocks with the same name then there will be similar issues with linking to a specific one. For example the docs for google_access_context_manager_service_perimeter has this appear 4 times in the HTML: <a name="nested_sources"></a>

I'll mark this issue as no longer upstream-terraform but I won't close it

SarahFrench commented 2 weeks ago

Note from triage: Renaming this issue to make it more generic

hashicorp / terraform-provider-google