[m4tx]

This adds an automated script that generates a Guide page about the
configuration by using JsonSchema of the config structures in config.rs.
In addition to that, there's a new test added to cot-test
that checks whether the markdown file in the repository is up to date.

This has two huge advantages:

1. There is a full specification of the config file now, making it much
   easier to find out what the correct values are.
2. The specification never gets out of date, because the CI pipeline
   forces the guide page to be updated.

The reason we store the markdown file in the repository instead of
generating it on the fly is mainly so that any changes to the
documentation can be easily reviewed.

The workflow is therefore as following:

1. A change is made to the config structures in config.rs.
2. The change author regenerates the guide with just generate-config-docs.
3. The changes are reviewed when a PR is made.
4. Whenever the generated result is not up to our standards, either the
   docs or the generation script is modified.

There are some limitations of the page generation script, such as:

• The script only takes the first paragraph of the rustdoc, so the links
  need to be inlined - referencing links defined later in the doc will
  not work.
• Some types are not supported - e.g. [cache.timeout] displays the
  type of the value is just string, even though it needs to be
  a specific string that represents a time duration.

The config page "cheats" a little bit to be more readable, e.g.
it reduces the padding of the content. See cot-rs/cot-site#111
for the details.

Fixes #479

[github-actions]

Bencher Report

Project	cot
Branch	toml-reference
Testbed	github-ubuntu-latest

Click to view all benchmark results

Benchmark	Latency	Benchmark Result milliseconds (ms) (Result Δ%)	Upper Boundary milliseconds (ms) (Limit %)
empty_router/empty_router	📈 view plot 🚷 view threshold	13.34 ms (+19.52%) Baseline: 11.16 ms	18.77 ms (71.07%)
json_api/json_api	📈 view plot 🚷 view threshold	1.12 ms (+11.40%) Baseline: 1.01 ms	1.34 ms (83.59%)
nested_routers/nested_routers	📈 view plot 🚷 view threshold	1.09 ms (+14.94%) Baseline: 0.95 ms	1.25 ms (87.42%)
single_root_route/single_root_route	📈 view plot 🚷 view threshold	1.02 ms (+11.78%) Baseline: 0.91 ms	1.21 ms (84.35%)
single_root_route_burst/single_root_route_burst	📈 view plot 🚷 view threshold	17.66 ms (+4.83%) Baseline: 16.84 ms	22.33 ms (79.06%)

🐰 View full continuous benchmarking report in Bencher

[Copilot]

Pull request overview

Adds an auto-generated TOML configuration reference to the documentation, sourced from cot::config::ProjectConfig via JSON Schema so the docs stay in sync with the actual config surface.

Changes:

• Introduces a schemars-based generator plus a cot-test test to enforce docs/configuration.md freshness.
• Adds a config-docs internal feature to enable JSON Schema derivation for config types.
• Wires the new configuration page into the docs site navigation and adds a just task to regenerate the docs.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
justfile	Adds a just generate-config-docs helper to regenerate the config reference.
docs/site/src/main.rs	Adds the new “Configuration” page to the docs site nav.
docs/configuration.md	New generated configuration reference page.
cot/src/email/transport/smtp.rs	Enables JSON Schema derivation for SMTP auth mechanism enum (for docs generation).
cot/src/config.rs	Adds JsonSchema derives / schema overrides to config types to support docs generation.
cot/Cargo.toml	Adds internal config-docs feature to drive schema generation.
cot-test/tests/config_reference.rs	Adds a test that fails if docs/configuration.md is out of date.
cot-test/src/lib.rs	Exposes the config reference generator behind config-docs.
cot-test/src/config_reference.rs	Implements the Markdown generator from the ProjectConfig schema.
cot-test/src/bin/generate_config_docs.rs	Adds a binary to write the generated docs file.
cot-test/Cargo.toml	Adds deps and feature wiring for the docs generator/test/bin.
Cargo.lock	Records new dependency additions for schema generation.

Comments suppressed due to low confidence (1)

cot/src/config.rs:1799

• Using schemars(with = "Option<String>") for expiry: Expiry implies the config schema accepts null, even though the TOML representation is a string and the field is defaulted (optional-by-omission, not nullable). Prefer schemars(with = "String") here to keep the schema accurate.

    #[cfg_attr(feature = "config-docs", schemars(with = "Option<String>"))]

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[m4tx]

The current screenshot:

[codecov]

Codecov Report

❌ Patch coverage is 93.23144% with 31 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cot-test/src/config_reference.rs	95.52%	15 Missing and 5 partials ⚠️
cot-test/src/bin/generate_config_docs.rs	0.00%	11 Missing ⚠️

Flag	Coverage Δ
rust	90.23% <93.23%> (+0.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
cot-test/src/lib.rs	76.76% <ø> (ø)
cot/src/config.rs	94.58% <ø> (ø)
cot/src/email/transport/smtp.rs	89.56% <ø> (ø)
cot-test/src/bin/generate_config_docs.rs	0.00% <0.00%> (ø)
cot-test/src/config_reference.rs	95.52% <95.52%> (ø)

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[seqre]

I get the idea behind showing that default here, but I don't like how it looks like, especially with the 3-column layout for the page the table is really narrow. I think I'd just link to section below where the default is visible

[ElijahAhianyo]

In my opinion, I think the current table is fine, considering that most default values are not long strings. Keeping the default value inline reduces the cognitive load of having to move between sections to find it.

That also draws my attention to cases like:

### [cache]
| `store` | `table` | `"type" = "memory"` |

### [`middlewares.session`]
| `store` | `table` | `"type" = "memory"` |

### [`email`]
| `transport` | `table` | `"type" = "console"` |

Shouldn't the default values for these say “see below,” just like sections likemiddlewares.live_load?

[m4tx]

@ElijahAhianyo I'm not sure if I get it. These config keys need to be specified with an enum variant, hence we have type = ... here. In case of middlewares.live_reload there is no enum; middlewares.live_reload is just a single struct, which means there's no default variant, and we have the "see below" link instead, which points to the list of all config keys, including their defaults.

Does that make sense?

[Copilot]

Copilot review overview

🟡 Changes recommended

Several generated defaults are inaccurate or incorrectly represented as required placeholders.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Distinguish null defaults from missing required defaults · New
• Expose redis pool size default in generated schema · New
• Use build-profile-dependent default for debug setting · New

Resolved since last review (3)

• Using schemars(with = "Option<String>") for timeout: Timeout implies the config schema accepts…
• The generator currently drops rustdoc link reference definitions, which leaves reference-style…
• schemars and serde_json are unconditional dependencies, so they’ll be compiled for all…