Skip to content

refactor(settings): use better serialization methods and types#194

Merged
water-sucks merged 4 commits intonix-community:mainfrom
water-sucks:use-toml-serialization-in-docs-formatter
Feb 23, 2026
Merged

refactor(settings): use better serialization methods and types#194
water-sucks merged 4 commits intonix-community:mainfrom
water-sucks:use-toml-serialization-in-docs-formatter

Conversation

@water-sucks
Copy link
Copy Markdown
Collaborator

@water-sucks water-sucks commented Feb 22, 2026

When generation documentation, the metadata was often stringly typed, which made serialization of values rather hard.

This was the case for showing default values for more complex TOML types such as maps and slices, as mentioned in #185, and also for showing examples, since these were often directly embedded as markdown in the description.

Let's not even MENTION the differences between scdoc manpages and Markdown! That was also a huge problem with this code.

This PR solves all those problems and uses actual fields in the settings description entries for any examples and deprecation notices, and formats them depending on if they're in a Markdown page or a man page.

Additionally, it serializes all default values using the underlying koanf TOML serializer (pelletier/go-toml), so no new dependencies are introduced.

Summary by CodeRabbit

  • Documentation

    • Enhanced settings documentation with improved TOML-formatted example values and defaults for better clarity.
    • Improved deprecation warnings that provide alternative suggestions when using deprecated settings.
  • Refactor

    • Updated internal settings validation and error handling mechanisms.

@water-sucks
Copy link
Copy Markdown
Collaborator Author

@coderabbitai review

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Feb 22, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Feb 22, 2026

📝 Walkthrough

Walkthrough

The changes refactor the settings documentation and validation system to introduce TOML-based rendering for configuration examples and defaults, add structured deprecation error handling, and expand settings metadata with Example and Deprecated fields for enhanced documentation.

Changes

Cohort / File(s) Summary
Documentation Generation
doc/build.go
Updated SettingsFormatter interface and implementations (MarkdownSettingsFormatter, ManpageSettingsFormatter) to accept exampleValue, defaultValue, and deprecated parameters. Added TOML marshaling logic to render example and default values with proper formatting (inline for scalars or fenced blocks for multi-line). Introduced indent helper for multi-line TOML block formatting.
Error Handling
internal/settings/errors.go
Changed SettingsErrors type from []SettingsError to []error to support broader error types. Added new DeprecatedSettingError struct with Field and Alternative fields, including Error() method for formatted output.
Settings Configuration
internal/settings/settings.go
Extended DescriptionEntry with Example (any) and Deprecated (string) fields. Updated SettingsDocs entries to populate new metadata fields for aliases, ssh.private_key_cmd, init.extra_attrs, init.extra_config, and no_confirm. Refactored validation logic to use DeprecatedSettingError for deprecation handling. Added map initialization for Aliases in NewSettings(). Removed bolded helper function.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes the main changes: refactoring settings to use better serialization (TOML-based rendering) and types (structured Example/Deprecated fields and DeprecatedSettingError).

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
  • 📝 Generate docstrings (stacked PR)
  • 📝 Generate docstrings (commit on current branch)
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.5.0)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
internal/settings/settings.go (1)

177-177: ⚠️ Potential issue | 🟡 Minor

Typo: "accesss" → "access"

 	"enter.mount_resolv_conf": {
-		Short: "Bind-mount host 'resolv.conf' inside chroot for internet accesss",
+		Short: "Bind-mount host 'resolv.conf' inside chroot for internet access",
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@internal/settings/settings.go` at line 177, Fix the typo in the command/flag
description: locate the Short string that currently reads "Bind-mount host
'resolv.conf' inside chroot for internet accesss" and change "accesss" to
"access" so the Short description reads "Bind-mount host 'resolv.conf' inside
chroot for internet access"; update the Short field where it is defined (the
command's Short property in settings.go).
🧹 Nitpick comments (2)
internal/settings/settings.go (1)

199-203: Minor inconsistency between Deprecated text and DeprecatedSettingError.Alternative.

Line 202: Deprecated: "Set \confirmation.always` to `true` instead." Line 333:Alternative: "set `confirmation.always` to `true` instead"`

The casing ("Set" vs "set") and trailing period differ. These appear in different contexts (docs vs CLI error), so it may be intentional, but worth normalizing for consistency.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@internal/settings/settings.go` around lines 199 - 203, Normalize the
deprecation message for the "no_confirm" setting to match the CLI error
alternative: update the Deprecated field in the "no_confirm" entry so it reads
exactly like DeprecatedSettingError.Alternative (use "set `confirmation.always`
to `true` instead" with the same casing and punctuation), ensuring both the
Deprecated string in the map and the Alternative value used by
DeprecatedSettingError are identical.
internal/settings/errors.go (1)

16-24: Embedded newline in Error() may surprise callers that expect single-line errors.

Go convention is for Error() to return a single-line string. The multi-line format with \nhint: ... works well for direct user display, but could produce unexpected output if the error is wrapped with fmt.Errorf("...: %w", err) or logged by a structured logger. If this is only used for user-facing CLI output, it's fine — just worth being intentional about.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@internal/settings/errors.go` around lines 16 - 24,
DeprecatedSettingError.Error() currently returns a multi-line string which can
surprise callers expecting a single-line error; change Error() to return a
single-line representation (e.g., combine e.Field, DeprecatedDocString and
e.Alternative into one line separated by punctuation like " - hint: " or
parentheses) and add a new method (e.g., DetailedMessage() or UserMessage())
that returns the multi-line, user-facing text for CLI output; update references
to use DetailedMessage() where multi-line hints are intended and keep Error() as
the concise single-line string to satisfy fmt.Errorf/loggers.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@doc/build.go`:
- Around line 293-296: The early "return" when defaultValue == nil causes the
function to exit before writing deprecated notices; instead, stop returning and
only skip rendering the default value so the deprecated block still runs.
Replace the "return" in the defaultValue == nil check with logic that continues
processing (e.g., "continue" if inside a loop) or otherwise skips outputting the
default value but allows the subsequent deprecated rendering code (the block
that writes the deprecation notice around lines where the deprecated message is
emitted) to execute; reference the defaultValue variable and the surrounding
deprecated-rendering code to find and update the flow.

In `@internal/settings/settings.go`:
- Around line 94-99: The example for ssh.private_key_cmd uses a bare slice
(Example = []string{"sh", "-c", "rbw get $NIXOS_CLI_SSH_HOST"}) which causes
toml.Marshal to panic; update the Example value (the DescriptionEntry.Example
usage) to be a map or struct wrapper (e.g. map[string]any{"command":
[]string{...}}) or a raw string so the TOML encoder won't attempt to emit a
root-level slice, and also correct the typo "internet accesss" to "internet
access" in the corresponding description text.

---

Outside diff comments:
In `@internal/settings/settings.go`:
- Line 177: Fix the typo in the command/flag description: locate the Short
string that currently reads "Bind-mount host 'resolv.conf' inside chroot for
internet accesss" and change "accesss" to "access" so the Short description
reads "Bind-mount host 'resolv.conf' inside chroot for internet access"; update
the Short field where it is defined (the command's Short property in
settings.go).

---

Nitpick comments:
In `@internal/settings/errors.go`:
- Around line 16-24: DeprecatedSettingError.Error() currently returns a
multi-line string which can surprise callers expecting a single-line error;
change Error() to return a single-line representation (e.g., combine e.Field,
DeprecatedDocString and e.Alternative into one line separated by punctuation
like " - hint: " or parentheses) and add a new method (e.g., DetailedMessage()
or UserMessage()) that returns the multi-line, user-facing text for CLI output;
update references to use DetailedMessage() where multi-line hints are intended
and keep Error() as the concise single-line string to satisfy
fmt.Errorf/loggers.

In `@internal/settings/settings.go`:
- Around line 199-203: Normalize the deprecation message for the "no_confirm"
setting to match the CLI error alternative: update the Deprecated field in the
"no_confirm" entry so it reads exactly like DeprecatedSettingError.Alternative
(use "set `confirmation.always` to `true` instead" with the same casing and
punctuation), ensuring both the Deprecated string in the map and the Alternative
value used by DeprecatedSettingError are identical.

@water-sucks water-sucks force-pushed the use-toml-serialization-in-docs-formatter branch from a7c4d18 to 01cd54e Compare February 23, 2026 00:15
@water-sucks water-sucks merged commit d723cf9 into nix-community:main Feb 23, 2026
2 checks passed
@water-sucks water-sucks deleted the use-toml-serialization-in-docs-formatter branch February 23, 2026 00:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant