docs: add auto-generated config TOML reference

cot-cli/src/migration_generator.rs

@@ -1172,11 +1172,13 @@ impl GeneratedMigration {
                 unreachable!("AddField operation should never create cycles")
             }
             DynOperation::RemoveField { .. } => {
-                // RemoveField doesn't create dependencies, it only removes a field
+                // RemoveField doesn't create dependencies, it only removes a
+                // field
                 unreachable!("RemoveField operation should never create cycles")
             }
             DynOperation::RemoveModel { .. } => {
-                // RemoveModel doesn't create dependencies, it only removes a model
+                // RemoveModel doesn't create dependencies, it only removes a
+                // model
                 unreachable!("RemoveModel operation should never create cycles")
             }
         }

cot-cli/src/new_project.rs

@@ -69,8 +69,9 @@ pub fn new_project(
     let dev_secret_key = generate_secret_key();
 
     for (file_name, content) in PROJECT_FILES {
-        // Cargo reads and parses all files that are named "Cargo.toml" in a repository,
-        // so we need a different name so that it doesn't fail on build.
+        // Cargo reads and parses all files that are named "Cargo.toml" in a
+        // repository, so we need a different name so that it doesn't
+        // fail on build.
         let file_name = file_name.replace(".template", "");
 
         let file_path = path.join(file_name);

cot-cli/src/utils.rs

@@ -419,7 +419,8 @@ mod tests {
             let package_name = temp_dir.path().file_name().unwrap().to_str().unwrap();
             test_utils::make_package(temp_dir.path()).unwrap();
 
-            // ensure the tests run sequentially when setting the current directory
+            // ensure the tests run sequentially when setting the current
+            // directory
             let _guard = serial_guard();
             std::env::set_current_dir(temp_dir.path().join("src")).unwrap();
 

cot-core/src/error/backtrace.rs

@@ -10,8 +10,8 @@ pub fn __cot_create_backtrace() -> Backtrace {
         if start {
             backtrace.push(frame);
         } else if frame.symbol_name().contains("__cot_create_backtrace") {
-            // TODO does this work with strip = true? (probably not, in that case we should
-            // return all frames instead)
+            // TODO does this work with strip = true? (probably not, in that
+            // case we should return all frames instead)
             start = true;
         }
 

cot-core/src/error/error_impl.rs

@@ -171,9 +171,10 @@ impl Error {
 
 impl Debug for Error {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        // If the alternate (`{:#?}`) formatting has been specified, print out the
-        // `Debug` formatting normally. If not, (which is the case when using
-        // `Result::unwrap()` or `Result::expect()`) pretty print the error.
+        // If the alternate (`{:#?}`) formatting has been specified, print out
+        // the `Debug` formatting normally. If not, (which is the case
+        // when using `Result::unwrap()` or `Result::expect()`) pretty
+        // print the error.
         if f.alternate() {
             Debug::fmt(&self.repr, f)
         } else {

cot-macros/src/form.rs

@@ -250,11 +250,11 @@ impl FormDeriveBuilder {
         let fields_as_dyn_field_ref = &self.fields_as_dyn_field_ref;
         let fields_as_display = &self.fields_as_display;
 
-        // <'dummy> is here because we can't directly create trivial constraints in
-        // where clauses
+        // <'dummy> is here because we can't directly create trivial constraints
+        // in where clauses
         // see https://github.com/rust-lang/rust/issues/48214 for details
-        // and the following comment for the details on the workaround being used here:
-        // https://github.com/rust-lang/rust/issues/48214#issuecomment-2557829956
+        // and the following comment for the details on the workaround being
+        // used here: https://github.com/rust-lang/rust/issues/48214#issuecomment-2557829956
         let fields_as_display_trait_bound = &self.fields_as_display_trait_bound;
         let display_where_clause = if fields_as_display_trait_bound.is_empty() {
             quote! {}

cot-test/Cargo.toml

@@ -18,12 +18,28 @@ cot-cli = { workspace = true, features = ["test_utils"] }
 cot.workspace = true
 glob.workspace = true
 libtest-mimic.workspace = true
+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/full", "cot/_internal_config-docs"]
+
 [lints]
 workspace = true
 
 [[test]]
 name = "doc_code_blocks"
 path = "tests/doc_code_blocks.rs"
 harness = false
+
+[[test]]
+name = "config_reference"
+path = "tests/config_reference.rs"
+required-features = ["config-docs"]
+
+[[bin]]
+name = "generate_config_docs"
+path = "src/bin/generate_config_docs.rs"
+required-features = ["config-docs"]

cot-test/src/bin/generate_config_docs.rs

@@ -0,0 +1,20 @@
+//! Regenerates `docs/configuration.md` from `cot::config::ProjectConfig`'s type
+//! definition.
+//!
+//! Run via `just generate-config-docs`.
+
+use std::path::PathBuf;
+
+fn main() {
+    let content = cot_test::config_reference::generate_config_reference();
+
+    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let docs_path = manifest_dir
+        .parent()
+        .expect("failed to get workspace path")
+        .join("docs")
+        .join("configuration.md");
+
+    std::fs::write(&docs_path, content).expect("failed to write docs/configuration.md");
+    println!("Wrote {}", docs_path.display());
+}