docs: add auto-generated config TOML reference#621
Draft
m4tx wants to merge 1 commit into
Draft
Conversation
m4tx
changed the title
github-actions
Bot
added
A-docs
|
Bencher Report| Project | cot |
| Branch | toml-reference |
| Testbed | github-ubuntu-latest |
🚨 1 Alert
| Benchmark | Measure Units | View | Benchmark Result (Result Δ%) | Upper Boundary (Limit %) |
|---|---|---|---|---|
| empty_router/empty_router | Latency milliseconds (ms) | 📈 plot 🚷 threshold 🚨 alert (🔔) | 13.03 ms(+79.68%)Baseline: 7.25 ms | 12.55 ms (103.84%) |
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 🚨 view alert (🔔) | 13.03 ms(+79.68%)Baseline: 7.25 ms | 12.55 ms (103.84%) |
| json_api/json_api | 📈 view plot 🚷 view threshold | 1.14 ms(+5.68%)Baseline: 1.08 ms | 1.37 ms (83.54%) |
| nested_routers/nested_routers | 📈 view plot 🚷 view threshold | 1.06 ms(+5.60%)Baseline: 1.01 ms | 1.24 ms (85.46%) |
| single_root_route/single_root_route | 📈 view plot 🚷 view threshold | 1.02 ms(+5.48%)Baseline: 0.97 ms | 1.21 ms (84.77%) |
| single_root_route_burst/single_root_route_burst | 📈 view plot 🚷 view threshold | 17.02 ms(-2.04%)Baseline: 17.37 ms | 21.69 ms (78.47%) |
Contributor
There was a problem hiding this comment.
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 acot-testtest to enforcedocs/configuration.mdfreshness. - Adds a
config-docsinternal feature to enable JSON Schema derivation for config types. - Wires the new configuration page into the docs site navigation and adds a
justtask 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>")forexpiry: Expiryimplies the config schema acceptsnull, even though the TOML representation is a string and the field is defaulted (optional-by-omission, not nullable). Preferschemars(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.
Comment on lines
+21
to
+27
| schemars = { workspace = true, features = ["std"] } | ||
| serde_json.workspace = true | ||
| thiserror.workspace = true | ||
|
|
||
| [features] | ||
| # Enables generating the configuration file reference (docs/configuration.md). | ||
| config-docs = ["cot/config-docs"] |
| /// timeout = "2h" | ||
| /// ``` | ||
| #[serde(with = "crate::serializers::cache_timeout")] | ||
| #[cfg_attr(feature = "config-docs", schemars(with = "Option<String>"))] |
Comment on lines
+447
to
+463
| fn first_paragraph(desc: &str) -> String { | ||
| let mut lines = Vec::new(); | ||
| for line in desc.lines() { | ||
| let trimmed = line.trim(); | ||
| if trimmed.starts_with('#') || trimmed.starts_with("```") { | ||
| break; | ||
| } | ||
| if trimmed.is_empty() { | ||
| if lines.is_empty() { | ||
| continue; | ||
| } | ||
| break; | ||
| } | ||
| lines.push(trimmed); | ||
| } | ||
| lines.join(" ") | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #479
Related issue or discussion
Description
Type of change