hashicorp / terraform-plugin-docs Goto Github PK
View Code? Open in Web Editor NEWGenerate and validate Terraform plugin/provider documentation.
License: Mozilla Public License 2.0
Generate and validate Terraform plugin/provider documentation.
License: Mozilla Public License 2.0
go mod init demo
go get github.com/hashicorp/terraform-plugin-framework
go get github.com/hashicorp/terraform-plugin-go
go get github.com/hashicorp/terraform-plugin-sdk/v2
cat go.mod
module demo
go 1.17
require (
github.com/hashicorp/terraform-plugin-framework v0.6.0 // indirect
github.com/hashicorp/terraform-plugin-go v0.8.0 // indirect
github.com/hashicorp/terraform-plugin-sdk/v2 v2.11.0 // indirect
)
go get github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs imports
github.com/hashicorp/terraform-plugin-docs/internal/cmd imports
github.com/hashicorp/terraform-plugin-docs/internal/provider imports
github.com/hashicorp/terraform-exec/tfinstall: cannot find module providing package github.com/hashicorp/terraform-exec/tfinstall
It would be useful to have at generation time a set of warnings when markdown is not properly linted.
Similar to the features provided by: https://github.com/bflad/tfproviderdocs
I've setup a docs/guides
folder containing human written content. When I run the go generate command, the guides subfolder is deleted.
I have a Terraform Provider which needs special tags to build.
These tags I can pass to:
go run -tags containers_image_openpgp github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
The problem is though, that tfplugindocs does not pass along the tags.
As a result tflugindocs fails building Go files.
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:17:16: undefined: gpgme.Context
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:67:44: undefined: gpgme.Context
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:68:14: undefined: gpgme.New
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:72:27: undefined: gpgme.ProtocolOpenPGP
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:76:28: undefined: gpgme.ProtocolOpenPGP
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:98:20: undefined: gpgme.NewDataBytes
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:127:20: undefined: gpgme.NewDataBytes
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:132:18: undefined: gpgme.NewDataWriter
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:136:25: undefined: gpgme.Key
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:136:61: undefined: gpgme.SigModeNormal
Error: /home/runner/go/pkg/mod/github.com/containers/image/[email protected]/signature/mechanism_gpgme.go:136:61: too many errors
Thus I would need a way for tfplugindocs to handle tags when generating code.
Hello ๐๐ป
I'm opening this more for a general discussion regarding the use of DefaultFunc
with a required field.
I've noticed that when adding DefaultFunc
to an otherwise required field it's rendered in the documentation as 'optional'.
Now this make sense because if the value isn't provided by the user in their configuration, then we'll use schema.EnvDefaultFunc
to get a value (otherwise we return an empty string), but it's also a little bit confusing when you look at the code and see Required: true
compared to the documentation saying it's 'optional'.
"user": {
Type: schema.TypeString,
Required: true,
DefaultFunc: schema.EnvDefaultFunc("SOME_ENV_VAR", ""),
}
I'm not sure if it's better to still have this field be shown as 'required' in the documentation because ultimately if the user doesn't provide a value (not in config, nor in the environment var) then we'll end up setting an empty string which will (in our case definitely) cause errors. I'd personally still prefer to see this field under "Required" to be explicit that regardless of the use of DefaultFunc
the user should pay special attention to it.
Thoughts?
Ability to run something like tfplugindocs serve
to browse the site locally.
If a resource has DeprecationMessage
field then a callout should be emitted to the generated Markdown.
Example:
When generating sections for documenting nested blocks, the generator creates a <a id="nestedblock--something"></a>
just above the markdown title level 3 that is generated ### Nested schema for something
and generates links that point to the former anchor instead of the one generated by the markdown title.
Issue is the id="nestedblock--something"
part of the HTML link is removed in the final docs on the registry (on the preview too), leaving only <a></a>
, so the anchor links are effectively broken.
See for example this page https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/monitor
Generated from https://github.com/DataDog/terraform-provider-datadog/blob/master/docs/resources/monitor.md
Using the tfplugindocs
v0.3.1
Now the question is: should this be fixed in the registry site where the markdown files are rendered to HTML, so that the id
attribute doesn't disappear, or should it be fixed in this generator so that it directly uses the id that the markdown titles will get after rendering.
Thanks for having a look !
And thanks for this docs generator !
Cheers
It looks like tfpluginfocs downloads the terraform binary each time it is run. We could work a lot quicker if we could tell tfplugindocs the location of a terraform binary to use instead.
I'd like to propose a new argument --terraform-binary [path]
for this purpose. When specified, tfplugindocs would use that terraform binary instead of downloading it. (This is analogous to Helmfile's --helm-binary
argument.)
Hello,
When running tfplugindocs inside my terraform plugin I have this error:
tfplugindocs.exe generate
rendering website for provider "terraform_ccc_provider"
exporting schema from Terraform
compiling provider "terraform_ccc_provider"
using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
running terraform init
Error executing command: unable to generate website: configuration is invalid
I cannot get any information on what is invalid and what this tool is expecting. Would be nice to have more informations on this kind of errors.
Can you help me?
Regards
As per Generating Documentation:
$ go get github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs imports
github.com/hashicorp/terraform-plugin-docs/internal/cmd imports
github.com/hashicorp/terraform-plugin-docs/internal/provider imports
github.com/hashicorp/terraform-exec/tfinstall imports
github.com/hashicorp/go-getter imports
cloud.google.com/go/storage imports
google.golang.org/api/option imports
google.golang.org/api/internal imports
google.golang.org/grpc/naming: cannot find module providing package google.golang.org/grpc/naming
$ go version
go version go1.17.8 darwin/amd64
Each terraform schema has an implicit ID
that needs to be set for the terraform lifecycle to work properly.
We don't set this "ID" explicitly in the schema, but the generated documentation seems to mark it as Optional
I think this should be marked as "Read Only" if the "ID" isn't explicitly in the schema by the provider developer.
Example Dashboard Resource Schema - https://github.com/DataDog/terraform-provider-datadog/blob/master/datadog/resource_datadog_dashboard.go#L44
Generated Documentation - https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/dashboard#optional
It seems like resource and data source templates have to be name specific. This request is providing the caller the ability to replace the const defaultResourceTemplate
. Then the provider developer does not have to provide a template per unique resource.
For the resource template excerpt:
# {{.Type}} `{{.Name}}`
v0.4.0 generates (for an AWS VPC resource, say):
# aws_vpc `Resource`
which is certainly backwards from the perspective of the rendered page, but surely it's right to expect that .Type
would be "Resource" and .Name
"aws_vpc", rather than vice versa?
I initially got that template from the Unifi provider linked in the readme here, but I note now that it doesn't use resource templates, and there's a sensible default if you don't need to add something to the template. So I've actually done that myself too now, and as a result this isn't really an issue for me, just thought I'd mention it ๐.
The descriptions of the nested elements are only rendered in the markdown of the resources
, but not the datasources
.
"ipam_config": {
Type: schema.TypeSet,
Description: "The IPAM configuration options",
Computed: true,
Elem: &schema.Resource{
Schema: map[string]*schema.Schema{
"subnet": {
Type: schema.TypeString,
Description: "The subnet in CIDR form",
Optional: true,
ForceNew: true,
},
"ip_range": {
Type: schema.TypeString,
Description: "The ip range in CIDR form",
Optional: true,
ForceNew: true,
},
"gateway": {
Type: schema.TypeString,
Description: "The IP address of the gateway",
Optional: true,
ForceNew: true,
},
"aux_address": {
Type: schema.TypeMap,
Description: "Auxiliary IPv4 or IPv6 addresses used by Network driver",
Optional: true,
ForceNew: true,
},
},
},
},
See the rendered markdowns:
The descriptions of the nested elements in datasources
are also rendered in the markdown.
v0.4.0
v2.6.1
Hi, I'm just curious if tfplugindocs
is still being worked on?
Just slightly worried to notice no commits for several months when quite active previously, except moving an Action from @paultyng's repo to Hashicorp's; that not authored or committed by him (instead @smacfarlane), who was previously the committer on almost all and authored most.
Thanks! ๐ค๐ป it's nothing, just a priority shift ๐
Running the tfplugindocs
from the root of any provider repo generates the following error:
โฏ tfplugindocs
rendering website for provider "terraform-provider-scaffolding"
exporting schema from Terraform
compiling provider "scaffolding"
Error executing command: unable to generate website: unexpected error: invalid checksum: no checksum found in: https://releases.hashicorp.com/terraform/0.13.2/terraform_0.13.2_SHA256SUMS
> ~/g/s/g/h/terraform-provider-scaffolding
Not sure what i'm doing incorrectly. I have tried on other repos terraform-provider-unifi
and same results
Related to the issue around deprecation in #10, if a resource is renamed, then it would be helpful to skip generating documentation for that resource.
One approach might be to take a command line flag for resources or filenames to skip in generation.
As mentioned in #10:
deprecation messages are not included in the schema exported from Terraform, only a bool indicating its deprecated
I propose making this bool available in the template rendering (as a workaround to this limitation). That way, it may be used in custom templates for documentation generation.
The AWS provider uses a GitHub action to do this, may be able to use similar functionality or the command its wrapping.
Potentially related to #5
test
When ForceNew is enabled on a field, the documentation should note the behavior. While the description could include these details, the behavior behind ForceNew: true
is generally consistent throughout providers and resources.
Originally from https://github.com/equinix/terraform-provider-metal/issues/110
Assume the following schema segment:
"quantity": {
Default: 30,
Description: "The quantity of this resource.",
Optional: true,
Type: schema.TypeInt,
}
When documentation is generated, fields are emitted with their type and a requirement "indicator":
quantity (Number, Optional) The quantity of this resource.
A default value should be emitted to the generated Markdown if specified in the underlying schema:
quantity (Number, Optional, Default: 30) The quantity of this resource.
Unfortunately in 2.x russross/blackfriday breaks compatibility, so we had to prevent Dependabot from just bumping it up.
This library is the markdown processor used by this project.
Despite this, we want to upgrade it to the latest stable version, but it will require an active implementation change.
(Block List)
as a type rendered in documentation makes sense to the maintainer of a provider, but IMO it's confusing or even misleading to the end user.
Concrete example here:
OJFord/terraform-provider-wireguard@58ef3d8#diff-60a95e399cf5c94cb98075600ad42997cdae1a9839f293569766d66acdaa0bcfR59
peer
in:
data "wireguard_config_document" "peer1" {
private_key = wireguard_asymmetric_key.peer1.private_key
listen_port = 1234
dns = [
"1.1.1.1",
"1.0.0.1",
"2606:4700:4700:0:0:0:0:64",
"2606:4700:4700:0:0:0:0:6400",
]
peer {
public_key = wireguard_asymmetric_key.peer2.public_key
allowed_ips = [
"0.0.0.0/0",
]
persistent_keepalive = 25
}
peer {
public_key = wireguard_asymmetric_key.peer3.public_key
endpoint = "example.com:51820"
allowed_ips = [
"::/0",
]
}
}
to a user isn't a 'list', it's just a block. One that can be specified multiple times, sure, and maybe that's represented as a list behind the scenes, but as someone using the resource or data source it isn't a list.
It's rendered in docs (by tfplugindocs
v0.4.0) as:
- peer (Block List) (see below for nested schema)
but I think better would be:
- peer (Block, repeatable) (see below for nested schema)
or 'multiple allowed', or similar.
Terraform allows providers to have empty objects in their schema, but currently terraform-plugin-docs does not recognize such empty fields neither as required, nor optional, nor read-only, and thus cannot generate docs for such providers and raises an error like the following:
no match for empty_block_field, this can happen if you have incompatible schema
defined, for example an optional block where all the child attributes are
computed, in which case the block itself should also be marked computed
I tried to fix it with this patch: #99
Only running in GH Actions CI (vs. my also-amd64 machine) and only if terraform
is already on $PATH
, v0.7.0 (which began to use it from PATH) errors:
using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
running terraform init
getting provider schema
Error executing command: unable to generate website: invalid character 'c' looking for beginning of value
(For example: https://github.com/OJFord/terraform-provider-wireguard/runs/5590511618)
I haven't been able to reproduce this outside of Actions, even using act
, which makes it quite difficult to debug.
I've worked around it by letting it acquire terraform itself instead.
Currently, when a field in a schema is deprecated, it shows up in parenthesis next to whether it's required or not.
Live example here under thresholds
- https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/monitor#optional
thresholds (Map of String, Deprecated) Alert thresholds of the monitor.
Could the fact that a field is deprecated be more strongly represented?
A few ideas for this may be -
Deprecated
bold to stand out moreRequired
, Optional
, Deprecated
Thanks for this project ๐
hi!
Is there any way to self host provider docs? We wrote some providers that are internal to our company.
We would like to generate docs for them using tfplugindocs
. I used this tool, but i just got MD files in the format expected by the registry.
Is there a way to convert these files to normal markdown files so that they can be hosted in Github pages, for eg?
There are two issues:
Description
field set on the parent Schema isn't displayed any where.Description
value pulled into the documentation.Here's an example schema that shows a Description
field has been set on the top-level Schema:
s.Schema[h.GetKey()] = &schema.Schema{
Type: schema.TypeSet,
Required: true,
Description: "A set of Domain names to serve as entry points for your Service",
Elem: &schema.Resource{
Schema: map[string]*schema.Schema{
"name": {
Type: schema.TypeString,
Required: true,
Description: "The domain that this Service will respond to",
},
"comment": {
Type: schema.TypeString,
Optional: true,
Description: "An optional comment about the Domain.",
},
},
},
}
Yet when generating the documentation for this resource I discovered that description value is not present anywhere:
Here's an example schema definition with a nested schema under the 'rules' field:
Schema: map[string]*schema.Schema{
"publishers": {
Type: schema.TypeList,
Optional: true,
Description: "A list of publishers to be used as filters for the data set.",
Elem: &schema.Schema{Type: schema.TypeString},
},
"tags": {
Type: schema.TypeList,
Optional: true,
Description: "A list of tags to be used as filters for the data set.",
Elem: &schema.Schema{Type: schema.TypeString},
},
"exclude_modsec_rule_ids": {
Type: schema.TypeList,
Optional: true,
Description: "A list of modsecurity rules IDs to be excluded from the data set.",
Elem: &schema.Schema{Type: schema.TypeInt},
},
"rules": {
Type: schema.TypeList,
Computed: true,
Description: "The list of rules that results from any given combination of filters.",
Elem: &schema.Resource{
Schema: map[string]*schema.Schema{
"modsec_rule_id": {
Type: schema.TypeInt,
Required: true,
Description: "The modsecurity rule ID.",
},
"latest_revision_number": {
Type: schema.TypeInt,
Required: true,
Description: "The modsecurity rule's latest revision.",
},
"type": {
Type: schema.TypeString,
Computed: true,
Description: "The modsecurity rule's type.",
},
},
},
},
},
In the generated schema output (see below example, from running tfplugindocs generate
) we can see the Description
fields from the top-level Schema
types are included in the output, but the nested Schema Description fields are not included (see <MISSING DESCRIPTION>
)...
<!-- schema generated by tfplugindocs -->
## Schema
### Optional
- **exclude_modsec_rule_ids** (List of Number) A list of modsecurity rules IDs to be excluded from the data set.
- **id** (String) The ID of this resource.
- **publishers** (List of String) A list of publishers to be used as filters for the data set.
- **tags** (List of String) A list of tags to be used as filters for the data set.
### Read-only
- **rules** (List of Object) The list of rules that results from any given combination of filters. (see [below for nested schema](#nestedatt--rules))
<a id="nestedatt--rules"></a>
### Nested Schema for `rules`
Read-only:
- **latest_revision_number** (Number) <MISSING DESCRIPTION>
- **modsec_rule_id** (Number) <MISSING DESCRIPTION>
- **type** (String) <MISSING DESCRIPTION>
Given the schema entry:
"rm": {
Type: schema.TypeBool,
Description: "If true, then the container will be automatically removed after his execution.",
Default: false,
Optional: true,
},
the rendered output is
- **rm** (Boolean) If true, then the container will be automatically removed after his execution.
I'd like to have Defaults to abc
in the generation as well as follows:
- **rm** (Boolean) If true, then the container will be automatically removed after his execution. Defaults to `false`
v0.4.0
v2.6.1
Just a feature idea - I realise it'll at best be a 'nice-to-have', far more to be done first sort of thing - but I think it'd be really helpful for working on provider docs; making sure the flow makes sense and everything renders correctly, to be able to serve a local preview roughly as it will render on the registry.
i.e. something like:
$tfplugindocs serve
Serving myprovider docs on http://localhost:8123
(And just to say - even without that, I'm already extremely glad to find this generator, early days as it may be. Beats the copy-pasting-renaming between projects I have been doing. ๐ Great stuff!)
example:
// service_account resource schema
func (r serviceAccountResourceType) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
return tfsdk.Schema{
MarkdownDescription: "Service account resource",
Attributes: map[string]tfsdk.Attribute{
"id": {
Type: types.StringType,
Computed: true,
MarkdownDescription: "Server generated UUID",
},
"name": {
Type: types.StringType,
Required: true,
Validators: []tfsdk.AttributeValidator{
validate.StringNotNull(),
},
},
"role": {
Type: types.StringType,
Required: true,
Validators: []tfsdk.AttributeValidator{
validate.RoleIsValid(),
},
},
"membership_id": {
Type: types.StringType,
Computed: true,
MarkdownDescription: "Server generated UUID",
},
},
}, nil
}
Both Description
and MarkdownDescription
are ignored.
github.com/hashicorp/terraform-plugin-docs v0.5.1
I hope this is a reasonable request! :D
I can't see to get this to tools.go
right in its current state, because the latest tag doesn't contain tfplugindocs. Causing some trouble building the docs for our provider out https://github.com/zerotier/terraform-provider-zerotier
If this is not possible please lmk how I can use your tool with go modules reliably.
I have been trying to make use of this project with terraform-provider-snowflake and am very excited for it, since it means I could delete my half-baked code that did similar work.
We have run into one limitation โ required provider configuration which accepts environment variables.
When using this configuration, running terraform providers schema -json
will vary its configuration for these inputs based on whether or not the environment variables are present. For the linked example, if the SNOWFLAKE_USER
environment variable is set, then username
will be marked as "optional". If the env variable is not preset, it will be set as "required".
For purposes of documentation, it seems like it should always be marked as "required".
I have created some terraform provider,
and it is need to create document so using this and modify but I have a hard time reproducing default.
I have copy and paste from template.go but something wrong...for example, not output Example Usage on index.md.
(What is {{ if .HasExample -}}
...?)
(this repo)/templates/*
Thank you.
I'm trying to generate docs for a custom provider, however the tool produces an error when it tries to render the following schema:
func manualTriggerSchema() map[string]*schema.Schema {
return map[string]*schema.Schema{
"trigger": {
Type: schema.TypeString,
Computed: true,
},
}
}
Which produces the following error:
Error executing command: unable to generate website: unable to render doc "gorillastack_rule": unable to render template for "gorillastack_rule": unable to render schema: unable to render schema: no match for "manual"
Adding a dummy 'required' attribute fixes this issue:
func manualTriggerSchema() map[string]*schema.Schema {
return map[string]*schema.Schema{
"trigger": {
Type: schema.TypeString,
Computed: true,
},
"dummy": {
Type: schema.TypeString,
Required: true,
},
}
}
Is it a requirement that a 'Required' attribute must be present in a schema or is this a bug within the tool?
Thanks.
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.
Hello!
I'm trying to run tfplugindocs
for the provider-terraform-hashicups
provider.
I am receiving the following error, can you point me in the right direction?
$ go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
rendering website for provider "terraform-provider-hashicups"
exporting schema from Terraform
compiling provider "hashicups"
2022/04/26 23:07:27 error executing "/usr/local/bin/go", [go build -o /var/folders/s6/m22_k3p11z104k2vx1jkqr2c0000gp/T/tfws2963541216/plugins/registry.terraform.io/hashicorp/hashicups/0.0.1/darwin_amd64/terraform-provider-hashicups]
2022/04/26 23:07:27 ../../../../pkg/mod/github.com/zclconf/[email protected]/cty/function/stdlib/format.go:9:2: missing go.sum entry for module providing package github.com/apparentlymart/go-textseg/v13/textseg (imported by github.com/zclconf/go-cty/cty/function/stdlib); to add:
go get github.com/zclconf/go-cty/cty/function/[email protected]
../../../../pkg/mod/github.com/hashicorp/[email protected]/internal/plugin/grpc_broker.pb.go:11:2: missing go.sum entry for module providing package golang.org/x/net/context (imported by github.com/hashicorp/go-plugin); to add:
go get github.com/hashicorp/[email protected]
../../../../pkg/mod/google.golang.org/[email protected]/internal/transport/controlbuf.go:28:2: missing go.sum entry for module providing package golang.org/x/net/http2 (imported by google.golang.org/grpc/internal/transport); to add:
go get google.golang.org/grpc/internal/[email protected]
../../../../pkg/mod/google.golang.org/[email protected]/internal/transport/controlbuf.go:29:2: missing go.sum entry for module providing package golang.org/x/net/http2/hpack (imported by google.golang.org/grpc/internal/transport); to add:
go get google.golang.org/grpc/internal/[email protected]
../../../../pkg/mod/google.golang.org/[email protected]/server.go:36:2: missing go.sum entry for module providing package golang.org/x/net/trace (imported by google.golang.org/grpc); to add:
go get google.golang.org/[email protected]
Error executing command: unable to generate website: error executing "/usr/local/bin/go": exit status 1
exit status 1
Currently a provider block with no schema (see the random provider) needs to be special cased, this should be able to be handled in the template.
For slightly silly/cautious reasons, I'm developing my provider in a folder that is different from the repo & providers name, which means that the docs are generated with the wrong name.
It would be good if we could pass in the name with via a -name
flag.
Currently, if I try to run the main.go directly with go I get the following errors. Could you have defaults such as undefined commit and devel version?
$ go run ./cmd/tfplugindocs/main.go
# command-line-arguments
cmd/tfplugindocs/main.go:13:34: undefined: version
cmd/tfplugindocs/main.go:14:5: undefined: commit
cmd/tfplugindocs/main.go:15:32: undefined: commit
As part of the upcoming Terraform CLI version 0.15 release, a newer version 6 of the Terraform Plugin Protocol is now available. This protocol bump includes goodies such as NestedType
that will benefit the future of plugin development and documentation. The changes to the output of terraform providers schema -json
are denoted with a bump in that format version from 0.1 to 0.2.
The readme describes using resource examples in examples/resources/<name>/resource.tf
, but if I template {{ printf "%s" .ExampleFile }}
it seems just to be ""
for resources.
After a quick look at the code, I think it's just not implemented rather than a bug. I'm sure you know this - a note here just might help anyone else confused by it.
To workaround, you can of course just change the template to remove the if .HasExample
and .ExampleFile
and replace with a tffile "examples/resources/wherever.tf"
. That is:
{{/* templates/resources/name.md.tmpl */}}
## Example Usage
{{ tffile "examples/resources/name/resource.tf" }}
It's more readable to use code block
for attribute names instead of bold
and also it makes attributes linkable.
It's also aligned with the docs of major terraform providers.
Given the schema entry with the surrounding type is and all attributes are Computed: true,
:
"network_data": {
Type: schema.TypeList,
Description: "The data of the networks the container is connected to",
Computed: true,
Elem: &schema.Resource{
Schema: map[string]*schema.Schema{
"network_name": {
Type: schema.TypeString,
Description: "The name of the network",
Computed: true,
},
"ip_address": {
Type: schema.TypeString,
Description: "The IP address of the container.",
Computed: true,
Deprecated: "Use `network_data` instead. The IP address of the container's first network it.",
},
"ip_prefix_length": {
Type: schema.TypeInt,
Description: "The IP prefix length of the container.",
Computed: true,
Deprecated: "Use `network_data` instead. The IP prefix length of the container as read from its NetworkSettings.",
},
"gateway": {
Type: schema.TypeString,
Description: "The network gateway of the container.",
Computed: true,
Deprecated: "Use `network_data` instead. The network gateway of the container as read from its NetworkSettings.",
},
"global_ipv6_address": {
Type: schema.TypeString,
Description: "The IPV6 address of the container",
Computed: true,
},
"global_ipv6_prefix_length": {
Type: schema.TypeInt,
Description: "The IPV6 prefix length address of the container",
Computed: true,
},
"ipv6_gateway": {
Type: schema.TypeString,
Description: "The IPV6 gateway of the container",
Computed: true,
},
},
},
},
the rendered output is
<a id="nestedatt--network_data"></a>
### Nested Schema for `network_data`
Read-Only:
- **gateway** (String)
- **global_ipv6_address** (String)
- **global_ipv6_prefix_length** (Number)
- **ip_address** (String)
- **ip_prefix_length** (Number)
- **ipv6_gateway** (String)
- **network_name** (String)
Where I like to see this output:
<a id="nestedblock--network_data"></a>
### Nested Schema for `network_data`
Read-Only:
- **gateway** (String, Deprecated) The network gateway of the container.
- **global_ipv6_address** (String) The IPV6 address of the container
- **global_ipv6_prefix_length** (Number) The IPV6 prefix length address of the container
- **ip_address** (String, Deprecated) The IP address of the container.
- **ip_prefix_length** (Number, Deprecated) The IP prefix length of the container.
- **ipv6_gateway** (String) The IPV6 gateway of the container
- **network_name** (String) The name of the network
For the surrounding type with Optional: true,
the rendering works as expected.
v0.4.0
v2.6.1
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.