From 519f443ec597d8f71ca8f6679df3b3ebd762beb5 Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Thu, 25 Feb 2021 13:35:01 -0500 Subject: [PATCH] check: Prefer `terraform` code block language over `hcl` in examples (#47) Reference: https://github.com/bflad/tfproviderdocs/issues/21 --- CHANGELOG.md | 4 ++++ check/contents/check_example_section.go | 4 ++-- check/contents/testdata/example/missing_heading.md | 2 +- check/contents/testdata/example/passing.md | 2 +- check/contents/testdata/example/wrong_code_block_language.md | 2 +- check/contents/testdata/example/wrong_heading_level.md | 2 +- check/contents/testdata/example/wrong_heading_text.md | 2 +- check/contents/testdata/full.md | 2 +- check/contents/testdata/title/missing_heading.md | 2 +- check/contents/testdata/title/passing.md | 2 +- .../website/docs/r/invalid/thing.html.markdown | 2 +- .../invalid-legacy-files/data_source_invalid_extension.txt | 2 +- .../data_source_invalid_frontmatter.html.markdown | 2 +- .../data_source_with_sidebar_current.html.markdown | 2 +- .../data_source_without_layout.html.markdown | 2 +- .../invalid-legacy-files/resource_invalid_extension.txt | 2 +- .../resource_invalid_frontmatter.html.markdown | 2 +- .../resource_with_sidebar_current.html.markdown | 2 +- .../resource_without_layout.html.markdown | 2 +- .../invalid-mixed-directories/docs/resources/thing.md | 2 +- .../docs/resources/invalid/thing.md | 2 +- .../data_source_invalid_extension.markdown | 2 +- .../invalid-registry-files/data_source_invalid_frontmatter.md | 2 +- .../invalid-registry-files/data_source_with_layout.md | 2 +- .../data_source_with_sidebar_current.md | 2 +- .../resource_invalid_extension.markdown | 2 +- .../invalid-registry-files/resource_invalid_frontmatter.md | 2 +- check/testdata/invalid-registry-files/resource_with_layout.md | 2 +- .../invalid-registry-files/resource_with_sidebar_current.md | 2 +- .../website/docs/d/thing.html.markdown | 2 +- .../website/docs/r/thing.html.markdown | 2 +- check/testdata/valid-legacy-files/data_source.html.markdown | 2 +- check/testdata/valid-legacy-files/resource.html.markdown | 2 +- .../website/docs/r/thing.html.markdown | 2 +- .../valid-registry-directories/docs/data-sources/thing.md | 2 +- .../valid-registry-directories/docs/resources/thing.md | 2 +- check/testdata/valid-registry-files/data_source.md | 2 +- check/testdata/valid-registry-files/resource.md | 2 +- 38 files changed, 42 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ae6f2a5..b790ccd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # v0.9.0 +BREAKING CHANGES + +* check: Prefer `terraform` code block language over `hcl` in examples with experimental `-enable-contents-check` flag + ENHANCEMENTS * check: Add `-provider-source` option (support Terraform CLI 0.13 and later `-providers-schema-json` file) diff --git a/check/contents/check_example_section.go b/check/contents/check_example_section.go index 793d2b2..6410abc 100644 --- a/check/contents/check_example_section.go +++ b/check/contents/check_example_section.go @@ -30,8 +30,8 @@ func (d *Document) checkExampleSection() error { for _, fencedCodeBlock := range section.FencedCodeBlocks { language := markdown.FencedCodeBlockLanguage(fencedCodeBlock, d.source) - if language != markdown.FencedCodeBlockLanguageHcl && language != markdown.FencedCodeBlockLanguageTerraform { - return fmt.Errorf("example section code block language (%s) should be: ```%s or ```%s", language, markdown.FencedCodeBlockLanguageHcl, markdown.FencedCodeBlockLanguageTerraform) + if language != markdown.FencedCodeBlockLanguageTerraform { + return fmt.Errorf("example section code block language (%s) should be: ```%s", language, markdown.FencedCodeBlockLanguageTerraform) } text := markdown.FencedCodeBlockText(fencedCodeBlock, d.source) diff --git a/check/contents/testdata/example/missing_heading.md b/check/contents/testdata/example/missing_heading.md index f5b1bc1..1290da7 100644 --- a/check/contents/testdata/example/missing_heading.md +++ b/check/contents/testdata/example/missing_heading.md @@ -1,6 +1,6 @@ Manages an Example Thing. -```hcl +```terraform resource "test_missing_heading" "example" { name = "example" } diff --git a/check/contents/testdata/example/passing.md b/check/contents/testdata/example/passing.md index 449199c..68918ac 100644 --- a/check/contents/testdata/example/passing.md +++ b/check/contents/testdata/example/passing.md @@ -1,6 +1,6 @@ ## Example Usage -```hcl +```terraform resource "test_passing" "example" { name = "example" } diff --git a/check/contents/testdata/example/wrong_code_block_language.md b/check/contents/testdata/example/wrong_code_block_language.md index a306f60..560aaab 100644 --- a/check/contents/testdata/example/wrong_code_block_language.md +++ b/check/contents/testdata/example/wrong_code_block_language.md @@ -1,6 +1,6 @@ ## Example Usage -```tf +```hcl resource "test_wrong_code_block_language" "example" { name = "example" } diff --git a/check/contents/testdata/example/wrong_heading_level.md b/check/contents/testdata/example/wrong_heading_level.md index 7300b4d..02f8f5c 100644 --- a/check/contents/testdata/example/wrong_heading_level.md +++ b/check/contents/testdata/example/wrong_heading_level.md @@ -1,6 +1,6 @@ # Example Usage -```hcl +```terraform resource "test_wrong_heading_level" "example" { name = "example" } diff --git a/check/contents/testdata/example/wrong_heading_text.md b/check/contents/testdata/example/wrong_heading_text.md index 9759150..8805002 100644 --- a/check/contents/testdata/example/wrong_heading_text.md +++ b/check/contents/testdata/example/wrong_heading_text.md @@ -1,6 +1,6 @@ ## Examples -```hcl +```terraform resource "test_wrong_heading_text" "example" { name = "example" } diff --git a/check/contents/testdata/full.md b/check/contents/testdata/full.md index f71e670..367023e 100644 --- a/check/contents/testdata/full.md +++ b/check/contents/testdata/full.md @@ -12,7 +12,7 @@ Manages a Test Full. ## Example Usage -```hcl +```terraform resource "test_full" "example" { name = "example" } diff --git a/check/contents/testdata/title/missing_heading.md b/check/contents/testdata/title/missing_heading.md index 21fd30a..d0b98ec 100644 --- a/check/contents/testdata/title/missing_heading.md +++ b/check/contents/testdata/title/missing_heading.md @@ -2,7 +2,7 @@ Manages an Example Thing. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/contents/testdata/title/passing.md b/check/contents/testdata/title/passing.md index 2d1c4f3..a69294d 100644 --- a/check/contents/testdata/title/passing.md +++ b/check/contents/testdata/title/passing.md @@ -4,7 +4,7 @@ Manages an Example Thing. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-legacy-directories/website/docs/r/invalid/thing.html.markdown b/check/testdata/invalid-legacy-directories/website/docs/r/invalid/thing.html.markdown index e682340..59bb04c 100644 --- a/check/testdata/invalid-legacy-directories/website/docs/r/invalid/thing.html.markdown +++ b/check/testdata/invalid-legacy-directories/website/docs/r/invalid/thing.html.markdown @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-legacy-files/data_source_invalid_extension.txt b/check/testdata/invalid-legacy-files/data_source_invalid_extension.txt index 54736ea..caee79a 100644 --- a/check/testdata/invalid-legacy-files/data_source_invalid_extension.txt +++ b/check/testdata/invalid-legacy-files/data_source_invalid_extension.txt @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-legacy-files/data_source_invalid_frontmatter.html.markdown b/check/testdata/invalid-legacy-files/data_source_invalid_frontmatter.html.markdown index 86def90..1cb8750 100644 --- a/check/testdata/invalid-legacy-files/data_source_invalid_frontmatter.html.markdown +++ b/check/testdata/invalid-legacy-files/data_source_invalid_frontmatter.html.markdown @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-legacy-files/data_source_with_sidebar_current.html.markdown b/check/testdata/invalid-legacy-files/data_source_with_sidebar_current.html.markdown index ebd4a04..510d48a 100644 --- a/check/testdata/invalid-legacy-files/data_source_with_sidebar_current.html.markdown +++ b/check/testdata/invalid-legacy-files/data_source_with_sidebar_current.html.markdown @@ -13,7 +13,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-legacy-files/data_source_without_layout.html.markdown b/check/testdata/invalid-legacy-files/data_source_without_layout.html.markdown index 3ab22c7..688fa59 100644 --- a/check/testdata/invalid-legacy-files/data_source_without_layout.html.markdown +++ b/check/testdata/invalid-legacy-files/data_source_without_layout.html.markdown @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-legacy-files/resource_invalid_extension.txt b/check/testdata/invalid-legacy-files/resource_invalid_extension.txt index e682340..59bb04c 100644 --- a/check/testdata/invalid-legacy-files/resource_invalid_extension.txt +++ b/check/testdata/invalid-legacy-files/resource_invalid_extension.txt @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-legacy-files/resource_invalid_frontmatter.html.markdown b/check/testdata/invalid-legacy-files/resource_invalid_frontmatter.html.markdown index bc2339a..0cd796a 100644 --- a/check/testdata/invalid-legacy-files/resource_invalid_frontmatter.html.markdown +++ b/check/testdata/invalid-legacy-files/resource_invalid_frontmatter.html.markdown @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-legacy-files/resource_with_sidebar_current.html.markdown b/check/testdata/invalid-legacy-files/resource_with_sidebar_current.html.markdown index fbb25f7..32ec468 100644 --- a/check/testdata/invalid-legacy-files/resource_with_sidebar_current.html.markdown +++ b/check/testdata/invalid-legacy-files/resource_with_sidebar_current.html.markdown @@ -13,7 +13,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-legacy-files/resource_without_layout.html.markdown b/check/testdata/invalid-legacy-files/resource_without_layout.html.markdown index 130093a..aa156f3 100644 --- a/check/testdata/invalid-legacy-files/resource_without_layout.html.markdown +++ b/check/testdata/invalid-legacy-files/resource_without_layout.html.markdown @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-mixed-directories/docs/resources/thing.md b/check/testdata/invalid-mixed-directories/docs/resources/thing.md index e682340..59bb04c 100644 --- a/check/testdata/invalid-mixed-directories/docs/resources/thing.md +++ b/check/testdata/invalid-mixed-directories/docs/resources/thing.md @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-registry-directories/docs/resources/invalid/thing.md b/check/testdata/invalid-registry-directories/docs/resources/invalid/thing.md index 130093a..aa156f3 100644 --- a/check/testdata/invalid-registry-directories/docs/resources/invalid/thing.md +++ b/check/testdata/invalid-registry-directories/docs/resources/invalid/thing.md @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-registry-files/data_source_invalid_extension.markdown b/check/testdata/invalid-registry-files/data_source_invalid_extension.markdown index 3ab22c7..688fa59 100644 --- a/check/testdata/invalid-registry-files/data_source_invalid_extension.markdown +++ b/check/testdata/invalid-registry-files/data_source_invalid_extension.markdown @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-registry-files/data_source_invalid_frontmatter.md b/check/testdata/invalid-registry-files/data_source_invalid_frontmatter.md index 1482271..224dcf7 100644 --- a/check/testdata/invalid-registry-files/data_source_invalid_frontmatter.md +++ b/check/testdata/invalid-registry-files/data_source_invalid_frontmatter.md @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-registry-files/data_source_with_layout.md b/check/testdata/invalid-registry-files/data_source_with_layout.md index 54736ea..caee79a 100644 --- a/check/testdata/invalid-registry-files/data_source_with_layout.md +++ b/check/testdata/invalid-registry-files/data_source_with_layout.md @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-registry-files/data_source_with_sidebar_current.md b/check/testdata/invalid-registry-files/data_source_with_sidebar_current.md index 6b9f82c..afc1af9 100644 --- a/check/testdata/invalid-registry-files/data_source_with_sidebar_current.md +++ b/check/testdata/invalid-registry-files/data_source_with_sidebar_current.md @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-registry-files/resource_invalid_extension.markdown b/check/testdata/invalid-registry-files/resource_invalid_extension.markdown index 130093a..aa156f3 100644 --- a/check/testdata/invalid-registry-files/resource_invalid_extension.markdown +++ b/check/testdata/invalid-registry-files/resource_invalid_extension.markdown @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-registry-files/resource_invalid_frontmatter.md b/check/testdata/invalid-registry-files/resource_invalid_frontmatter.md index a737a2e..39a2823 100644 --- a/check/testdata/invalid-registry-files/resource_invalid_frontmatter.md +++ b/check/testdata/invalid-registry-files/resource_invalid_frontmatter.md @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-registry-files/resource_with_layout.md b/check/testdata/invalid-registry-files/resource_with_layout.md index e682340..59bb04c 100644 --- a/check/testdata/invalid-registry-files/resource_with_layout.md +++ b/check/testdata/invalid-registry-files/resource_with_layout.md @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/invalid-registry-files/resource_with_sidebar_current.md b/check/testdata/invalid-registry-files/resource_with_sidebar_current.md index c91e08c..91e6dcb 100644 --- a/check/testdata/invalid-registry-files/resource_with_sidebar_current.md +++ b/check/testdata/invalid-registry-files/resource_with_sidebar_current.md @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/valid-legacy-directories/website/docs/d/thing.html.markdown b/check/testdata/valid-legacy-directories/website/docs/d/thing.html.markdown index 54736ea..caee79a 100644 --- a/check/testdata/valid-legacy-directories/website/docs/d/thing.html.markdown +++ b/check/testdata/valid-legacy-directories/website/docs/d/thing.html.markdown @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/valid-legacy-directories/website/docs/r/thing.html.markdown b/check/testdata/valid-legacy-directories/website/docs/r/thing.html.markdown index e682340..59bb04c 100644 --- a/check/testdata/valid-legacy-directories/website/docs/r/thing.html.markdown +++ b/check/testdata/valid-legacy-directories/website/docs/r/thing.html.markdown @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/valid-legacy-files/data_source.html.markdown b/check/testdata/valid-legacy-files/data_source.html.markdown index 54736ea..caee79a 100644 --- a/check/testdata/valid-legacy-files/data_source.html.markdown +++ b/check/testdata/valid-legacy-files/data_source.html.markdown @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/valid-legacy-files/resource.html.markdown b/check/testdata/valid-legacy-files/resource.html.markdown index e682340..59bb04c 100644 --- a/check/testdata/valid-legacy-files/resource.html.markdown +++ b/check/testdata/valid-legacy-files/resource.html.markdown @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/valid-mixed-directories/website/docs/r/thing.html.markdown b/check/testdata/valid-mixed-directories/website/docs/r/thing.html.markdown index e682340..59bb04c 100644 --- a/check/testdata/valid-mixed-directories/website/docs/r/thing.html.markdown +++ b/check/testdata/valid-mixed-directories/website/docs/r/thing.html.markdown @@ -12,7 +12,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/valid-registry-directories/docs/data-sources/thing.md b/check/testdata/valid-registry-directories/docs/data-sources/thing.md index 3ab22c7..688fa59 100644 --- a/check/testdata/valid-registry-directories/docs/data-sources/thing.md +++ b/check/testdata/valid-registry-directories/docs/data-sources/thing.md @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/valid-registry-directories/docs/resources/thing.md b/check/testdata/valid-registry-directories/docs/resources/thing.md index 130093a..aa156f3 100644 --- a/check/testdata/valid-registry-directories/docs/resources/thing.md +++ b/check/testdata/valid-registry-directories/docs/resources/thing.md @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" } diff --git a/check/testdata/valid-registry-files/data_source.md b/check/testdata/valid-registry-files/data_source.md index 3ab22c7..688fa59 100644 --- a/check/testdata/valid-registry-files/data_source.md +++ b/check/testdata/valid-registry-files/data_source.md @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform data "example_thing" "example" { name = "example" } diff --git a/check/testdata/valid-registry-files/resource.md b/check/testdata/valid-registry-files/resource.md index 130093a..aa156f3 100644 --- a/check/testdata/valid-registry-files/resource.md +++ b/check/testdata/valid-registry-files/resource.md @@ -11,7 +11,7 @@ Byline. ## Example Usage -```hcl +```terraform resource "example_thing" "example" { name = "example" }