Hi,
I’m not sure if this is the right place to ask, but I did a lot of search and found nothing on the topic besides https://github.com/segmentio/terraform-docs, which doesn’t seem to be what I need since I want to document a custom provider and not terraform configuration/a module.
I’m talking about writing a custom provider as described here: https://www.terraform.io/docs/extend/writing-custom-providers.html
And about documentation like e.g. for the terraform aws provder as can be found here: https://www.terraform.io/docs/providers/aws/index.html
This kind of documentation (what resources do I have, what parameters do they accept, what are their defaults or are they required, computed or deprecated …) already exists in the schema code of the provider.
So I bet there is a tool to extract that information an render a documentation from it.
But I can’t seem to find that bit of information about how to do this and with what tool.
Can anybody help with that?
Hi @Heiko-san,
At the moment, the documentation you see on the Terraform website is maintained manually in Markdown format. There is no automatic tool for generating that documentation from the schema, because the documentation usually includes additional information that the schema cannot represent.
From Terraform v0.12.0 onwards there is a tool built in to Terraform for retrieving provider schemas in JSON format: terraform providers schema -json. As far as I know, nobody has yet written the second tool that would take that result and render it to HTML or to Markdown.
Hi,
thanks. That is what I found yesterday, too. And actually I planed to utilize that for a generator tool. 
The idea is to use mkdocs to render md files under docs/ , but in the first place append an automatically generated section to the manually written examples or something like that.
ls docs/
data_sources index.md provider.md resources
Where index.md is actually a symlink to provider.md (for mkdocs) and data_sources and resources are folders containing provider_resource.md files (in terms of the howto e.g. example_server.md) with something like
# example_server
Manage a server on the example cloud.
## my examples
...
And a script will search based on folder for resource_schemas or data_source_schemas in the json and append a ## inputs and ## outputs (computed fields) section to the corresponding md file.
After that mkdocs will render the result.
PS: I think it would be great if the schema would also provide the default (at least if it is a literal Default and not a DefaultFunc), ForceNew, ConflictsWith and maybe Deprecated & Removed.