internal/exec/docs_generate.go (5)

104-104: 🛠️ Refactor suggestion

Consider making 'README.yaml' filename configurable

Instead of hardcoding 'README.yaml', allow the filename to come from the configuration for greater flexibility.

---

117-117: 🛠️ Refactor suggestion

Update error message for clarity

Change the error message to reflect that we're generating Terraform docs within atmos, not running an external command.

-return fmt.Errorf("failed to run terraform-docs: %w", err)
+return fmt.Errorf("failed to generate terraform docs: %w", err)

---

156-169: 🛠️ Refactor suggestion

Reuse existing HTTP fetch methods

Use the existing methods (like go-getter) for HTTP fetching to handle authentication (e.g., GITHUB_TOKEN) and avoid duplicating code.

---

239-239: 🛠️ Refactor suggestion

Use consistent HTTP fetch methods for templates

Consider using the same HTTP fetching mechanisms used elsewhere to handle authentication and maintain consistency.

---

276-295: 🛠️ Refactor suggestion

Leverage existing deep merge functionality

Reuse atmos's native deep merging capabilities (possibly using mergo) instead of implementing a custom deepMerge function.

cmd/docs_generate.go (1)

9-9: Fix typo in comment

Correct the typo: "genrates" should be "generates".

-// docsGenerateCmd genrates README.md
+// docsGenerateCmd generates README.md

internal/exec/template_utils.go (2)

226-234: Add function documentation.

Consider adding a detailed function documentation comment that explains:

• The purpose of the function
• Parameter descriptions
• Return value descriptions
• Usage examples

+// ProcessTmplWithDatasourcesGomplate parses and executes Go templates with datasources using Gomplate.
+// It processes the template specified by tmplName and tmplValue using the provided merged data.
+//
+// Parameters:
+//   - atmosConfig: The Atmos configuration
+//   - settingsSection: Settings for template processing
+//   - tmplName: Name of the template
+//   - tmplValue: The template content
+//   - mergedData: Data to be used in template processing
+//   - ignoreMissingTemplateValues: If true, missing values are replaced with empty strings
+//
+// Returns:
+//   - string: The processed template
+//   - error: Any error that occurred during processing
 func ProcessTmplWithDatasourcesGomplate(

---

246-259: Enhance error handling for temporary file operations.

The temporary file operations could benefit from more robust cleanup and detailed error messages.

 tmpfile, err := os.CreateTemp("", "gomplate-data-*.json")
 if err != nil {
-    return "", fmt.Errorf("failed to create temp data file for gomplate: %w", err)
+    return "", fmt.Errorf("failed to create temporary data file for gomplate (pattern: gomplate-data-*.json): %w", err)
 }
 tmpName := tmpfile.Name()
-defer os.Remove(tmpName)
+defer func() {
+    if err := os.Remove(tmpName); err != nil {
+        // Log the error but don't fail the operation
+        u.LogWarning(atmosConfig, fmt.Sprintf("failed to remove temporary file %s: %v", tmpName, err))
+    }
+}()

pkg/schema/schema.go (2)

195-204: Add field documentation for TerraformDocsSettings.

Consider adding documentation comments for each field to explain their purpose and valid values.

 type TerraformDocsSettings struct {
+    // Enabled determines if Terraform documentation generation is active
     Enabled       bool   `yaml:"enabled,omitempty" json:"enabled,omitempty" mapstructure:"enabled,omitempty"`
+    // Format specifies the output format (e.g., "markdown", "asciidoc")
     Format        string `yaml:"format,omitempty" json:"format,omitempty" mapstructure:"format,omitempty"`
+    // ShowProviders controls whether provider documentation is included
     ShowProviders bool   `yaml:"show_providers,omitempty" json:"show_providers,omitempty" mapstructure:"show_providers,omitempty"`
+    // ShowInputs controls whether input variable documentation is included
     ShowInputs    bool   `yaml:"show_inputs,omitempty" json:"show_inputs,omitempty" mapstructure:"show_inputs,omitempty"`
+    // ShowOutputs controls whether output variable documentation is included
     ShowOutputs   bool   `yaml:"show_outputs,omitempty" json:"show_outputs,omitempty" mapstructure:"show_outputs,omitempty"`
+    // SortBy defines the sorting criteria for documentation elements (e.g., "name", "required")
     SortBy        string `yaml:"sort_by,omitempty" json:"sort_by,omitempty" mapstructure:"sort_by,omitempty"`
+    // HideEmpty determines if empty sections should be omitted from the output
     HideEmpty     bool   `yaml:"hide_empty,omitempty" json:"hide_empty,omitempty" mapstructure:"hide_empty,omitempty"`
+    // IndentLevel specifies the number of spaces to use for indentation
     IndentLevel   int    `yaml:"indent_level,omitempty" json:"indent_level,omitempty" mapstructure:"indent_level,omitempty"`
 }

---

206-211: Enhance DocsGenerate struct with documentation and validation.

Consider adding field documentation and validation tags to ensure proper usage.

 type DocsGenerate struct {
+    // Input is a list of paths to input files (e.g., README.yaml)
+    // At least one input file must be specified
     Input     []string              `yaml:"input,omitempty" json:"input,omitempty" mapstructure:"input"`
+    // Template is a list of template files to be used for generation
+    // At least one template file must be specified
     Template  []string              `yaml:"template,omitempty" json:"template,omitempty" mapstructure:"template"`
+    // Output specifies the path where the generated documentation will be written
     Output    string                `yaml:"output,omitempty" json:"output,omitempty" mapstructure:"output"`
+    // Terraform contains settings specific to Terraform documentation generation
     Terraform TerraformDocsSettings `yaml:"terraform,omitempty" json:"terraform,omitempty" mapstructure:"terraform"`
 }

atmos.yaml (1)

398-404: Consider making paths more configurable.

The hardcoded paths could be made more flexible by supporting:

• Environment variable substitution
• Relative path resolution
• Multiple file patterns

       input:
-        - "./README.yaml"
+        - "${ATMOS_README_INPUT:-./README.yaml}"
+        - "**/*.yaml"  # Support recursive search
       template:
-        - "./README.md.gotmpl"
+        - "${ATMOS_README_TEMPLATE:-./README.md.gotmpl}"
+        - "https://raw.githubusercontent.com/org/repo/main/templates/*.gotmpl"
       output: "README.md"

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

internal/exec/file_utils.go (2)

101-124: Strong implementation with clear documentation! 💪

The function effectively handles path conversion for both Windows and Linux systems, with excellent documentation and examples.

Consider optimizing the Windows path handling.

The Windows path handling could be simplified using an unconditional TrimPrefix:

-		if strings.HasPrefix(pathSlashed, "/") {
-			pathSlashed = strings.TrimPrefix(pathSlashed, "/")
-		}
+		pathSlashed = strings.TrimPrefix(pathSlashed, "/")

🧰 Tools

🪛 golangci-lint (1.62.2)

112-112: S1017: should replace this if statement with an unconditional strings.TrimPrefix

(gosimple)

---

126-142: Consider making the drive letter check more explicit! 🎯

The drive letter check on line 136 could be more explicit about its purpose:

-		if strings.HasPrefix(u.Path, "/") && len(u.Path) > 2 && u.Path[2] == ':' {
+		// Check if path starts with a drive letter (e.g., "/C:/...")
+		if strings.HasPrefix(u.Path, "/") && len(u.Path) > 2 && 
+			((u.Path[1] >= 'A' && u.Path[1] <= 'Z') || (u.Path[1] >= 'a' && u.Path[1] <= 'z')) && 
+			u.Path[2] == ':' {

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

atmos.yaml (2)

394-394: Use a single space after the colon.

The template key currently has two spaces after the colon. For YAML style consistency, please use only one space.

-      template:  "https://raw.githubusercontent.com/cloudposse/.github/5a599e3b929f871f333cb9681a721d26b237d8de/README.md.gotmpl"
+      template: "https://raw.githubusercontent.com/cloudposse/.github/5a599e3b929f871f333cb9681a721d26b237d8de/README.md.gotmpl"

🧰 Tools

🪛 YAMLlint (1.35.1)

[warning] 394-394: too many spaces after colon

(colons)

---

406-406: Remove trailing whitespace.

Line 406 has extra spaces at the end; trimming them will avoid lint errors.

-        indent_level: 2   
+        indent_level: 2

🧰 Tools

🪛 YAMLlint (1.35.1)

[error] 406-406: trailing spaces

(trailing-spaces)

tests/fixtures/scenarios/docs-generate/atmos.yaml (2)

32-32: Use a single space after the colon.

The template line has two spaces after the colon—standardize to one.

-      template:  "./README.md.gotmpl"
+      template: "./README.md.gotmpl"

🧰 Tools

🪛 YAMLlint (1.35.1)

[warning] 32-32: too many spaces after colon

(colons)

---

44-44: Eliminate trailing spaces.

Remove the unnecessary whitespace at the end of this line to satisfy YAML lint.

-        indent_level: 2 
+        indent_level: 2

🧰 Tools

🪛 YAMLlint (1.35.1)

[error] 44-44: trailing spaces

(trailing-spaces)

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

Learnt from: Listener430
PR: cloudposse/atmos#934
File: tests/fixtures/scenarios/docs-generate/README.md:14-23
Timestamp: 2025-01-25T03:44:52.619Z
Learning: Test fixtures under `tests/fixtures/` should not be modified unless the test case itself needs to change, as they are deliberately set up to represent specific scenarios for testing purposes.

Learnt from: RoseSecurity
PR: cloudposse/atmos#797
File: pkg/list/atmos.yaml:213-214
Timestamp: 2024-11-25T17:17:15.703Z
Learning: The file `pkg/list/atmos.yaml` is primarily intended for testing purposes.

tests/fixtures/scenarios/docs-generate/terraform/atmos.yaml (2)

32-32: Fix spacing after colon in template key.

Line 32 has two spaces after the colon, which is inconsistent with YAML style. It should be a single space:

-      template:  "./README.md.gotmpl"
+      template: "./README.md.gotmpl"

🧰 Tools

🪛 YAMLlint (1.35.1)

[warning] 32-32: too many spaces after colon

(colons)

---

44-44: Remove trailing whitespace.

Line 44 ends with an extra space. Trim the trailing space so it reads:

-        indent_level: 2 
+        indent_level: 2

🧰 Tools

🪛 YAMLlint (1.35.1)

[error] 44-44: trailing spaces

(trailing-spaces)

tests/fixtures/scenarios/docs-generate/input-variants/atmos.yaml (3)

30-30: Remove trailing whitespace in input list.

Line 30 has extra spaces at the end. Trim it to:

-        - "./README-local.yaml"  
+        - "./README-local.yaml"

🧰 Tools

🪛 YAMLlint (1.35.1)

[error] 30-30: trailing spaces

(trailing-spaces)

---

36-36: Fix spacing after colon in template key.

Line 36 contains two spaces after the colon. Update to a single space:

-      template:  "./README.md.gotmpl"
+      template: "./README.md.gotmpl"

🧰 Tools

🪛 YAMLlint (1.35.1)

[warning] 36-36: too many spaces after colon

(colons)

---

39-39: Add newline at end of file.

The file is missing a terminating newline. Add a blank line at the end to comply with POSIX standards.

tests/test-cases/docs-generate.yaml (2)

23-23: Trim trailing spaces.

There's trailing whitespace after "## Providers". Remove it:

-          - "## Providers" 
+          - "## Providers"

🧰 Tools

🪛 YAMLlint (1.35.1)

[error] 23-23: trailing spaces

(trailing-spaces)

---

72-72: Ensure newline at end of file and remove trailing spaces.

The YAML file should end with a single newline and no trailing spaces on the last line. Please add the newline and strip any trailing whitespace.

🧰 Tools

🪛 YAMLlint (1.35.1)

[error] 72-72: no new line character at the end of file

(new-line-at-end-of-file)

---

[error] 72-72: trailing spaces

(trailing-spaces)

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

Learnt from: RoseSecurity
PR: cloudposse/atmos#797
File: pkg/list/atmos.yaml:213-214
Timestamp: 2024-11-25T17:17:15.703Z
Learning: The file `pkg/list/atmos.yaml` is primarily intended for testing purposes.

website/docs/cli/commands/docs/docs-generate.mdx (4)

10-16: Add comma after “e.g.” in purpose note
Stylistically, “e.g.” should be followed by a comma. Please update the sentence accordingly.

-Use this command to generate one of your documentation artifacts (e.g. a README) as defined by the **named** section under `docs.generate.<KEY>` in `atmos.yaml`.
+Use this command to generate one of your documentation artifacts (e.g., a README) as defined by the **named** section under `docs.generate.<KEY>` in `atmos.yaml`.

🧰 Tools

🪛 LanguageTool

[style] ~12-~12: A comma is missing here.
Context: ...te one of your documentation artifacts (e.g. a README) as defined by the named s...

(EG_NO_COMMA)

---

20-46: Ensure the YAML code block is closed
The opening yaml fence at line 20 must have a matching closing fence to render correctly. Please verify there’s a after the release-notes snippet (around line 46).

---

67-68: Add comma after “By default” in Terraform docs note
For grammatical clarity, insert a comma after “By default” and adjust the list punctuation.

-The resultant file will also have a corresponding section rendered. By default `terraform.format` is set to `markdown table`, and can also be `markdown`, `tfvars hcl`, and `tfvars json`.
+The resultant file will also have a corresponding section rendered. By default, `terraform.format` is set to `markdown table`, and can also be `markdown`, `tfvars hcl`, or `tfvars json`.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~67-~67: Did you mean: “By default,”?
Context: ... have a corresponding section rendered. By default terraform.format is set to `markdown ...

(BY_DEFAULT_COMMA)

---

[grammar] ~67-~67: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...By default terraform.format is set to markdown table, and can also be markdown, `tf...

(MARKDOWN_NNP)

---

127-130: Consider adding concrete remote source examples
While you mention that remote files use go-getter, including a few example URLs or Git URIs (e.g., git::https://github.com/...) would help users understand valid remote syntaxes.

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro