Open paultyng opened 4 years ago
Has any thought been given on how to implement this?
I've started putting something together that reuses https://registry.terraform.io/tools/doc-preview to avoid having duplicate implementations of the rendering of the markdown. While there are a number of things that still need to be done (mostly marked with TODO comments), would this be acceptable?
My implementation proxies requests to the doc preview page and injects enough JavaScript to show the page and support switching the content of the textarea to display the other pages.
https://github.com/wjam/terraform-plugin-docs/commit/c488aaff8ee280c3f7f7476edec2b42ec5a2a7a1
Found this gem while working on a terraform provider.
@wjam I really like the approach for the local preview to reuse the Terraform registry doc preview tool. It is a real time saver when reviewing the documentation.
When trying the implementation at https://github.com/wjam/terraform-plugin-docs/commit/c488aaff8ee280c3f7f7476edec2b42ec5a2a7a1, the browser debugger shows errors related to the X-Content-Type-Options
header. I guess this is related to recent security enhancements in the browser.
Starting from https://github.com/wjam/terraform-plugin-docs/commit/c488aaff8ee280c3f7f7476edec2b42ec5a2a7a1, I added the following improvements and resolved some open TODOs:
httputil.ReverseProxy
in proxyRequest
; this fixed the X-Content-Type-Options
header violations mentions earliergo:embed
--addr [host:port]
cmd
to serve
Checkout the improved tfplugindocs serve
in https://github.com/dominik-lekse/terraform-plugin-docs/tree/serve-docs
@paultyng Do you have an update on the planing/roadmap of the preview feature?
The approach to inject javascript/markdown in the proxy is not ideal. However, it serves the purpose well as it includes a working navigation between resources and data sources like in the real terraform registry docs.
When going with the proxy approach, one direction could be to improve the registry doc preview tool to integrate nicer with the proxy (e.g. provide a javascript function to render the markdown to avoid the textarea injection).
A fully offline preview would of course require all assets of the preview tool to be embedded in tfplugindocs
and would not need a proxy. At this point, I am not sure if the source of the registry doc preview tool is available to the public.
This will be really helpful when developing provider. There are several use cases here:
Same use case with @spikewang.
@paultyng Is there any roadmap for an offline site of terraform plugin docs?
Ability to run something like
tfplugindocs serve
to browse the site locally.