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.

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

Link to resources, data sources and module sources docs #190

Open
richeney opened this issue Jun 18, 2020 · 7 comments
Open

Link to resources, data sources and module sources docs #190

richeney opened this issue Jun 18, 2020 · 7 comments
Labels
enhancement New feature or request modules Functionality related to the module block and modules generally providers Functionality related to Terraform providers textDocument/documentLink textDocument/hover upstream/tf-registry

Comments

@richeney
Copy link

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.

@richeney richeney changed the title Links through to Terraform documentation and module repos Link to Terraform documentation and module repos Jun 18, 2020
@radeksimko radeksimko transferred this issue from hashicorp/vscode-terraform Jun 26, 2020
@radeksimko
Copy link
Member

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:

Screenshot 2020-06-26 at 16 14 56

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
Copy link

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
Copy link
Member

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.

@radeksimko radeksimko changed the title Link to Terraform documentation and module repos Link to resources, data sources and module sources Feb 23, 2021
@radeksimko radeksimko changed the title Link to resources, data sources and module sources Link to resources, data sources and module sources docs Feb 25, 2021
@nfx
Copy link

nfx commented Feb 27, 2021

@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
Copy link

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.

@xiehan xiehan added modules Functionality related to the module block and modules generally providers Functionality related to Terraform providers labels Apr 21, 2023
@baalimago
Copy link

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
Copy link

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? 🙏

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request modules Functionality related to the module block and modules generally providers Functionality related to Terraform providers textDocument/documentLink textDocument/hover upstream/tf-registry
Projects
None yet
Development

No branches or pull requests

8 participants