Link to resources, data sources and module sources docs

[richeney]

Link to Terraform documentation and module repos

Enhancement summary

1. Resource type and data type become follow links to the matching documentation pages.
2. The values for a module's source argument also become follow links for known URI formats.

This would be a major productivity benefit!

Resource Type Example

For example, if I have

resource "azurerm_resource_group" "example" {
  name     = "example"
  location = "West Europe"
}

then make azurerm_resource_group a follow link (CTRL+click) to https://www.terraform.io/docs/providers/azurerm/r/resource_group.html.

If a data source then azurerm_resource_group would target https://www.terraform.io/docs/providers/azurerm/d/resource_group.html.

Module Source Example

Example module:

module "web_pool1_vms" {
  source            = "github.com/terraform-azurerm-modules/terraform-azurerm-linux-vm?ref=v0.1"
  defaults          = local.web_vm_defaults
  module_depends_on = [module.web_pool1_set]

  attachType = "ApplicationGateway"
  attach     = module.web_pool1_set.set_ids

  names           = ["web-pool1-a", "web-pool1-b", "web-pool1-c"]
  source_image_id = data.azurerm_image.ubuntu_18_04.id
}

Make github.com/terraform-azurerm-modules/terraform-azurerm-linux-vm?ref=v0.1 a follow link to https://github.com/terraform-azurerm-modules/terraform-azurerm-linux-vm?ref=v0.1.

[radeksimko]

Hi @richeney
This sounds like a feature that could likely be implemented in the language server, rather than on the client side (such as VSCode extension) - that's why I decided to transfer it here.

We do have plans to build hover support - there is already a draft PR - that isn't adding a link to docs yet, but I would imagine that would be a place where we can add it, similar to how gopls does it:

As far as clicking goes I think that is generally represented in LSP in the form of "go to definition" - something we haven't implemented yet either, but I would imagine that it's more likely we would be linking to the source code of the module cached locally.

The implementation details are not set in stone, but it will need to work within the boundaries of the LSP and conventions. With that in mind I haven't seen any language server linking directly (on click) to an external URL yet, but my view may be limited, so I would be curious to see if there are any examples of such behaviour in VSCode extension or any other IDE.

[adamrushuk]

It's great to see the hover support just come in for v0.10.0, so really looking forward to adding links to the documentation too. I believe the old Terraform extension had this functionality, but from memory I think you had to Ctrl + Click the resource name to turn it into a link.

[radeksimko]

Just FYI I have just released 0.14.0 version which comes with links to provider docs as per #402

We don't yet have predictable/stable deeplinks to resources or data sources on the Registry, so some more upstream work will need to be done before we can introduce it on the language server side.

Also I created #418 to track similar feature for core schema.

[nfx]

@radeksimko why links do you think that links are not predictable on the registry? there's generic convention, that's imposed on every plugin developer to create markdown files in a very specific format, so that registry is consistent:

e.g. for azurerm_resource_group we already have a stable URL https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/resource_group#location, which can be standardized as
https://registry.terraform.io/providers/{{NAMESPACE}}/{{PREFIX}}/latest/docs/resources/{{RESOURCE_WITHOUT_PREFIX}}#{{FIELD}}. data resources have the same behavior.

Shortcut may be applied as Plugin developers, who do not document their providers according to standards won't have documentation links working by this extension. E.g. it's totally fine for VSCode plugin to open a link that does not exist.

[nikolaik]

Would love to see this! Also, having resources, data sources and module sources link to the provider docs belonging to the object in question would be a useful first step.

[baalimago]

Hi! I'd like to have a crack at implementing this as a first potential addition to terraform-ls.

I've read through https://github.com/hashicorp/terraform-ls/blob/main/docs/architecture.md and plan to use #402 as a starting point and extend it for resources.

We don't yet have predictable/stable deeplinks to resources or data sources on the Registry, so some more upstream work will need to be done before we can introduce it on the language server side.

I figured I'd get adding common patterns for larger providers such as aws, gcp and azure, then map provider -> provider resource URL pattern for the links. My thinking is that these provider patterns may be configurable as well, so that users may add their own (or submit them as default). Perhaps also a 'test-query' where t-ls checks that the resource returns 200, before linking the user (may also include certificate validation etc to ensure links are safe).

Do you guys accept PR's? If so, any hints/tips/tricks for this one?

[runofthemill]

This would be a great addition;

@baalimago re: Do you guys accept PR's? If so, any hints/tips/tricks for this one?, CONTRIBUTING.md definitely encourages code contributions, though asks for a discussion up front prior to implementation:

In order to be respectful of the time of community contributors, we prefer to discuss potential changes in GitHub issues prior to implementation. That will allow us to give design feedback up front and set expectations about the scope of the change, and, for larger changes, how best to approach the work such that the maintainer team can review it and merge it along with other concurrent work.

If the bug you wish to fix or enhancement you wish to implement isn't already covered by a GitHub issue that contains feedback from the maintainer team, please do start a discussion (either in a new GitHub issue or an existing one, as appropriate) before you invest significant development time. If you mention your intent to implement the change described in your issue, the maintainer team can prioritize including implementation-related feedback in the subsequent discussion.

maybe @radeksimko or another member can give feedback? 🙏