Default placeholders and required flags (#1)

* Adjusted default flags * Moved to custom handling of required flags
giantswarm · Apr 28, 2023 · ddb06b2 · ddb06b2
1 parent 0e16af2
commit ddb06b2
Show file tree

Hide file tree

Showing 13 changed files with 21 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -22,7 +22,7 @@ go install github.com/giantswarm/schemadocs@latest
 Executing `schemadocs generate` without any options will generate Markdown documentation from a JSON schema file and store it in a `README.md` file in the current working directory. 
 
 It is required that the README file contains exactly one pair of placeholder strings, which mark the start and end of the documentation. 
-By default, the placeholders are `{::comment} # DOCS_START {/:comment}` and `{::comment} # DOCS_END {/:comment}`.
+By default, the placeholders are `<!-- DOCS_START -->` and `<!-- DOCS_END -->`.
 
 If the README file does not exist or in case it does not contain one pair of valid placeholder strings, the execution will fail.
 
@@ -32,7 +32,7 @@ $ schemadocs generate schema.json
 Generating documentation
 Schema: schema.json
 Destination file: README.md
-Using default placeholders '{::comment} # DOCS_START {:/comment}' and '{::comment} # DOCS_END {:/comment}'
+Using default placeholders '<!-- DOCS_START -->' and '<!-- DOCS_END -->'
 
 [SUCCESS] Documentation generated successfully!
 ```
@@ -41,7 +41,7 @@ To generate the documentation to a custom file, apply the `--output-path` option
 To use a pair of custom placeholder strings, apply the `--doc-placeholder-start` and `--doc-placeholder-end`.
 
 ```nohighlight
-$ schemadocs generate schema.json --output-path README.md --doc-placeholder-start [DOCS_START] --doc-placeholder-end [DOCS_END]
+$ schemadocs generate schema.json --output-path README.md --doc-placeholder-start <!-- DOCS_START --> --doc-placeholder-end <!-- DOCS_END -->
 ```
 
 **Note:** The `--doc-placeholder-start` and `--doc-placeholder-end` need to be provided as a pair. So, if one of them is specified, the other one needs to be specified, too.
@@ -54,7 +54,7 @@ Validate documentation in a text file by comparing it to documentation generated
 The validation passes in case both documentations match exactly.
 
 It is required that the text file contains exactly one pair of placeholder strings, which mark the start and end of the documentation.
-By default, the placeholders are `{::comment} # DOCS_START {/:comment}` and `{::comment} # DOCS_END {/:comment}`.
+By default, the placeholders are `<!-- DOCS_START -->` and `<!-- DOCS_END -->`.
 
 If the text file or the schema file do not exist or in case the text file does not contain one pair of valid placeholder strings, the execution will fail.
 
@@ -64,7 +64,7 @@ $ schemadocs validate README.md --schema schema.json
 Validating documentation
 Source file: README.md
 Schema file: schema.json
-Using default placeholders '{::comment} # DOCS_START {:/comment}' and '{::comment} # DOCS_END {:/comment}'
+Using default placeholders '<!-- DOCS_START -->' and '<!-- DOCS_END -->'
 
 [SUCCESS] Documentation is valid!
 ```

diff --git a/cmd/generate/command.go b/cmd/generate/command.go
@@ -16,7 +16,7 @@ By default the documentation will be stored to README.md file in the current wor
 Use --output-path / -o to specify a target path.
 
 The output file needs to contain placeholders indicating the start and end of the documentation,
-Default placeholders are {::comment} # DOCS_START {/:comment} and {::comment} # DOCS_END {/:comment}.
+Default placeholders are <!-- DOCS_START --> and <!-- DOCS_END -->.
 Use --doc-placeholder-start and --doc-placeholder-end to specify different placeholders.
 `
 	example = `  schemadocs generate schema.json

diff --git a/cmd/testdata/output_format_generate_success.golden.txt b/cmd/testdata/output_format_generate_success.golden.txt
@@ -1,6 +1,6 @@
 Generating documentation
 Schema: %[1]s
 Destination file: %[2]s
-Using default placeholders '{::comment} # DOCS_START {:/comment}' and '{::comment} # DOCS_END {:/comment}'
+Using default placeholders '<!-- DOCS_START -->' and '<!-- DOCS_END -->'
 
 [SUCCESS] Documentation generated successfully!
diff --git a/cmd/testdata/output_format_validate_failure_3.golden.txt b/cmd/testdata/output_format_validate_failure_3.golden.txt
@@ -1,7 +1,7 @@
 Validating documentation
 Source file: %[1]s
 Schema file: %[2]s
-Using default placeholders '{::comment} # DOCS_START {:/comment}' and '{::comment} # DOCS_END {:/comment}'
+Using default placeholders '<!-- DOCS_START -->' and '<!-- DOCS_END -->'
 
 [ERROR] Failed to validate documentation
 Reason: invalid schema file: jsonschema file://%[2]s compilation failed: open %[2]s: no such file or directory
diff --git a/cmd/testdata/output_format_validate_failure_4.golden.txt b/cmd/testdata/output_format_validate_failure_4.golden.txt
@@ -1,7 +1,7 @@
 Validating documentation
 Source file: %[1]s
 Schema file: %[2]s
-Using default placeholders '{::comment} # DOCS_START {:/comment}' and '{::comment} # DOCS_END {:/comment}'
+Using default placeholders '<!-- DOCS_START -->' and '<!-- DOCS_END -->'
 
 [FAILURE] Documentation is not valid
 Reason: invalid documentation error: documentation from readme %[1]s do not match output generated from %[2]s

diff --git a/cmd/testdata/output_format_validate_success.golden.txt b/cmd/testdata/output_format_validate_success.golden.txt
@@ -1,6 +1,6 @@
 Validating documentation
 Source file: %[1]s
 Schema file: %[2]s
-Using default placeholders '{::comment} # DOCS_START {:/comment}' and '{::comment} # DOCS_END {:/comment}'
+Using default placeholders '<!-- DOCS_START -->' and '<!-- DOCS_END -->'
 
 [SUCCESS] Documentation is valid!
diff --git a/cmd/testdata/readme.md b/cmd/testdata/readme.md
@@ -1,5 +1,5 @@
-{::comment} # DOCS_START {:/comment}
+<!-- DOCS_START -->
 
 
 
-{::comment} # DOCS_END {:/comment}
+<!-- DOCS_END -->
diff --git a/cmd/testdata/readme_diff.md b/cmd/testdata/readme_diff.md
@@ -1,5 +1,5 @@
-{::comment} # DOCS_START {:/comment}
+<!-- DOCS_START -->
 
 Docs
 
-{::comment} # DOCS_END {:/comment}
+<!-- DOCS_END -->
diff --git a/cmd/validate/command.go b/cmd/validate/command.go
@@ -16,7 +16,7 @@ to the documentation generated from the provided JSON schema.
 Use --schema to specify the JSON schema.
 
 The input text file needs to contain placeholders indicating the start and end of the documentation,
-Default placeholders are "{::comment} # DOCS_START {/:comment}" and "{::comment} # DOCS_END {/:comment}".
+Default placeholders are <!-- DOCS_START --> and <!-- DOCS_END -->.
 Use --doc-placeholder-start and --doc-placeholder-end to specify different placeholders.
 `
 	example = `  schemadocs validate README.md --schema schema.json

diff --git a/cmd/validate/flag.go b/cmd/validate/flag.go
@@ -22,8 +22,6 @@ func (f *flag) Init(cmd *cobra.Command) {
 	cmd.Flags().StringVar(&f.schema, flagSchema, "", "Path to the JSON schema file")
 	cmd.Flags().StringVar(&f.docPlaceholderStart, flagDocPlaceholderStart, "", "Placeholder string marking the start of the docs section in the output file")
 	cmd.Flags().StringVar(&f.docPlaceholderEnd, flagDocPlaceholderEnd, "", "Placeholder string marking the end of the docs section in the output file")
-
-	_ = cmd.MarkFlagRequired(flagSchema)
 }
 
 func (f *flag) Validate() error {

diff --git a/pkg/readme/readme.go b/pkg/readme/readme.go
@@ -10,8 +10,8 @@ const (
 	defaultOutputPath1      = "./README.md"
 	defaultOutputPath2      = "./Readme.md"
 	defaultOutputPath3      = "./readme.md"
-	defaultStartPlaceholder = "{::comment} # DOCS_START {:/comment}"
-	defaultEndPlaceholder   = "{::comment} # DOCS_END {:/comment}"
+	defaultStartPlaceholder = "<!-- DOCS_START -->"
+	defaultEndPlaceholder   = "<!-- DOCS_END -->"
 )
 
 type Readme struct {

diff --git a/pkg/readme/testdata/readme1.md b/pkg/readme/testdata/readme1.md
@@ -2,7 +2,7 @@
 
 Text
 
-{::comment} # DOCS_START {:/comment}
+<!-- DOCS_START -->
 
 ### Other
 
@@ -11,6 +11,6 @@ Text
 | `id` | **ID** - Unique identifier|**Type:** `string`<br/>|
 
 
-{::comment} # DOCS_END {:/comment}
+<!-- DOCS_END -->
 
 Text
diff --git a/pkg/readme/testdata/readme2.md b/pkg/readme/testdata/readme2.md
@@ -2,10 +2,10 @@
 
 Text
 
-{::comment} # DOCS_START {:/comment}
+<!-- DOCS_START -->
 
 Docs
 
-{::comment} # DOCS_END {:/comment}
+<!-- DOCS_END -->
 
 Text