search

hashicorp / terraform-plugin-docs

Generate and validate Terraform plugin/provider documentation.
Mozilla Public License 2.0
222 stars 69 forks source link

Add offline emulation of the site #5

Open paultyng opened 4 years ago

paultyng commented 4 years ago

Ability to run something like tfplugindocs serve to browse the site locally.

wjam commented 3 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

dominik-lekse commented 2 years ago

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:

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.

spikewang commented 2 years ago

This will be really helpful when developing provider. There are several use cases here:

  1. We want to visualize and validate before publishing the new version of the provider to the registry... I could try to generate one website based on markdown, but it won't be always rendered the same as registry...
  2. We want to host our internal documentation site to always point to the latest dev branch before publishing to registry. This will serve everyone internally who want to test the latest.
yufeiminds commented 1 year ago

Same use case with @spikewang.

@paultyng Is there any roadmap for an offline site of terraform plugin docs?