Documentation
¶
Overview ¶
importdocs-gen generates live/import-grammar.json, one row per TF resource type parsed from the provider's own Import documentation (issue #52, dispatched from #55: the source that kills both the 114 hand-authored composite separators and the manual "rule-1" check the Lambda pilot paid by hand - see internal/live/identity/table.go's "Registry-ratified" comment for what that check found by hand, aws_lambda_alias and aws_lambda_layer_version_permission).
For every TF type in live/survey-full.json's whole-provider roster, it fetches website/docs/r/<name>.html.markdown at the pinned provider release tag (GitHub raw content, hashicorp/terraform-provider-aws, v6.58.0 - the same release tools/survey-gen surveys), caching each file on disk the way tools/registry-gen caches its zip, so a full ~1400-file sweep costs the network exactly once. A 404 (a TF-side alias documented under a different canonical name, like aws_alb under lb.html.markdown) is cached and counted, not an error.
Each doc's "## Import" section is parsed for: the literal example import ID a `terraform import` command or import block shows, the single character that joins a composite ID's segments (only when the doc states or shows it unambiguously), and whether the ID is built from configuration arguments (cross-checked against the doc's own Argument Reference names) versus a server-assigned opaque value. See parse.go's classifyGrammar for the two signals this draws on and how they combine. Conservative by design: composed_of_arguments and separator are null whenever the doc does not resolve them with confidence - a wrong separator is worse than an admitted unknown.
Usage, from anywhere in the checkout:
go run ./tools/importdocs-gen
It needs network for the first fetch of each doc (or a warm cache under the OS user cache directory). -limit restricts the sweep to the first N types in the roster, for a fast dev/test loop:
go run ./tools/importdocs-gen -limit 50
-accept stamps the artifact header's accepted field with today's date, the same vocabulary and reasoning tools/survey-gen's own -accept flag documents (issue #37, increment 1): omitting it leaves the field unset, so an unreviewed regeneration shows up in the diff as the accepted date disappearing.
Source Files