cuprated: auto config docs (#418)

* auto config docs

* fmt & change arg

* fix clippy

* add comment_out functionality

* remove config files + gen in mdbook build

* review fixes

* Update books/user/src/config.md

Co-authored-by: hinto-janai <hinto.janai@protonmail.com>

---------

Co-authored-by: hinto-janai <hinto.janai@protonmail.com>

Author: Boog900

.gitignore

@@ -3,3 +3,4 @@ target/
 monerod
 books/*/book
 fast_sync_hashes.bin
+/books/user/Cuprated.toml

Cargo.lock

@@ -140,6 +140,7 @@ tokio-stream          = { version = "0.1", default-features = false }
 tokio                 = { version = "1", default-features = false }
 tower                 = { git = "https://github.com/Cuprate/tower.git", rev = "6c7faf0", default-features = false } # <https://github.com/tower-rs/tower/pull/796>
 toml                  = { version = "0.8", default-features = false }
+toml_edit             = { version = "0.22", default-features = false }
 tracing-appender      = { version = "0.2", default-features = false }
 tracing-subscriber    = { version = "0.3", default-features = false }
 tracing               = { version = "0.1", default-features = false }

Cargo.toml

@@ -73,6 +73,7 @@ tokio-util            = { workspace = true, features = ["rt"] }
 tokio-stream          = { workspace = true }
 tokio                 = { workspace = true }
 toml                  = { workspace = true, features = ["parse", "display"]}
+toml_edit             = { workspace = true }
 tower                 = { workspace = true }
 tracing-appender      = { workspace = true }
 tracing-subscriber    = { workspace = true, features = ["std", "fmt", "default"] }

binaries/cuprated/Cargo.toml

@@ -3,6 +3,7 @@ use std::{
     fs::{read_to_string, File},
     io,
     path::Path,
+    str::FromStr,
     time::Duration,
 };
 
@@ -30,13 +31,29 @@ mod storage;
 mod tokio;
 mod tracing_config;
 
+#[macro_use]
+mod macros;
+
 use fs::FileSystemConfig;
 use p2p::P2PConfig;
 use rayon::RayonConfig;
 use storage::StorageConfig;
 use tokio::TokioConfig;
 use tracing_config::TracingConfig;
 
+/// Header to put at the start of the generated config file.
+const HEADER: &str = r"##     ____                      _
+##    / ___|   _ _ __  _ __ __ _| |_ ___
+##   | |  | | | | '_ \| '__/ _` | __/ _ \
+##   | |__| |_| | |_) | | | (_| | ||  __/
+##    \____\__,_| .__/|_|  \__,_|\__\___|
+##              |_|
+##
+## All these config values can be set to their default by commenting them out with #.
+## Some values are already commented out, to set the value remove the # at the start of the line.
+
+";
+
 /// Reads the args & config file, returning a [`Config`].
 pub fn read_config_and_args() -> Config {
     let args = args::Args::parse();
@@ -76,32 +93,76 @@ pub fn read_config_and_args() -> Config {
     args.apply_args(config)
 }
 
-/// The config for all of Cuprate.
-#[derive(Debug, Default, Deserialize, Serialize, PartialEq)]
-#[serde(deny_unknown_fields, default)]
-pub struct Config {
-    /// The network we should run on.
-    network: Network,
+config_struct! {
+    /// The config for all of Cuprate.
+    #[derive(Debug, Deserialize, Serialize, PartialEq)]
+    #[serde(deny_unknown_fields, default)]
+    pub struct Config {
+        /// The network we should run on.
+        ///
+        /// Valid values: ["Mainnet", "Testnet" and "Stagenet"]
+        pub network: Network,
 
-    pub no_fast_sync: bool,
+        /// Enable/disable fast sync.
+        ///
+        /// Fast sync skips verification of old blocks by comparing block hashes to a built-in hash file,
+        /// disabling this will significantly increase sync time. New blocks are still fully validated.
+        pub fast_sync: bool,
 
-    /// [`tracing`] config.
-    pub tracing: TracingConfig,
+        #[child = true]
+        /// The tracing/log output config.
+        pub tracing: TracingConfig,
 
-    pub tokio: TokioConfig,
+        #[child = true]
+        /// The tokio config.
+        ///
+        /// Tokio is the async threadpool, used for network operations and the major service inside `cuprated`.
 
-    pub rayon: RayonConfig,
+        pub tokio: TokioConfig,
+        #[child = true]
+        /// The rayon config.
+        ///
+        /// Rayon is the CPU threadpool, used for CPU intensive tasks.
+        pub rayon: RayonConfig,
 
-    /// The P2P network config.
-    p2p: P2PConfig,
+        #[child = true]
+        /// The P2P network config.
+        pub p2p: P2PConfig,
 
-    /// The storage config.
-    pub storage: StorageConfig,
+        #[child = true]
+        /// The storage config.
+        pub storage: StorageConfig,
 
-    pub fs: FileSystemConfig,
+        #[child = true]
+        /// The filesystem config.
+        pub fs: FileSystemConfig,
+    }
+}
+
+impl Default for Config {
+    fn default() -> Self {
+        Self {
+            network: Default::default(),
+            fast_sync: true,
+            tracing: Default::default(),
+            tokio: Default::default(),
+            rayon: Default::default(),
+            p2p: Default::default(),
+            storage: Default::default(),
+            fs: Default::default(),
+        }
+    }
 }
 
 impl Config {
+    /// Returns a default [`Config`], with doc comments.
+    pub fn documented_config() -> String {
+        let str = toml::ser::to_string_pretty(&Self::default()).unwrap();
+        let mut doc = toml_edit::DocumentMut::from_str(&str).unwrap();
+        Self::write_docs(doc.as_table_mut());
+        format!("{HEADER}{doc}")
+    }
+
     /// Attempts to read a config file in [`toml`] format from the given [`Path`].
     ///
     /// # Errors
@@ -193,30 +254,13 @@ impl Config {
 mod test {
     use toml::from_str;
 
-    use crate::constants::EXAMPLE_CONFIG;
-
     use super::*;
 
-    /// Tests the latest config is the `Default`.
     #[test]
-    fn config_latest() {
-        let config: Config = from_str(EXAMPLE_CONFIG).unwrap();
-        assert_eq!(config, Config::default());
-    }
+    fn documented_config() {
+        let str = Config::documented_config();
+        let conf: Config = from_str(&str).unwrap();
 
-    /// Tests backwards compatibility.
-    #[test]
-    fn config_backwards_compat() {
-        // (De)serialization tests.
-        #[expect(
-            clippy::single_element_loop,
-            reason = "Remove after adding other versions"
-        )]
-        for version in ["0.0.1"] {
-            let path = format!("config/{version}.toml");
-            println!("Testing config serde backwards compat: {path}");
-            let string = read_to_string(path).unwrap();
-            from_str::<Config>(&string).unwrap();
-        }
+        assert_eq!(conf, Config::default());
     }
 }

binaries/cuprated/config/0.0.1.toml

@@ -5,7 +5,7 @@ use serde_json::Value;
 
 use cuprate_helper::network::Network;
 
-use crate::{config::Config, constants::EXAMPLE_CONFIG, version::CupratedVersionInfo};
+use crate::{config::Config, version::CupratedVersionInfo};
 
 /// Cuprate Args.
 #[derive(clap::Parser, Debug)]
@@ -61,7 +61,7 @@ impl Args {
         }
 
         if self.generate_config {
-            println!("{EXAMPLE_CONFIG}");
+            println!("{}", Config::documented_config());
             exit(0);
         }
     }
@@ -71,7 +71,7 @@ impl Args {
     /// This may exit the program if a config value was set that requires an early exit.
     pub const fn apply_args(&self, mut config: Config) -> Config {
         config.network = self.network;
-        config.no_fast_sync = config.no_fast_sync || self.no_fast_sync;
+        config.fast_sync = config.fast_sync && !self.no_fast_sync;
 
         if let Some(outbound_connections) = self.outbound_connections {
             config.p2p.clear_net.general.outbound_connections = outbound_connections;

binaries/cuprated/config/Cuprated.toml

@@ -4,11 +4,21 @@ use serde::{Deserialize, Serialize};
 
 use cuprate_helper::fs::{CUPRATE_CACHE_DIR, CUPRATE_DATA_DIR};
 
-#[derive(Debug, Deserialize, Serialize, PartialEq, Eq)]
-#[serde(deny_unknown_fields, default)]
-pub struct FileSystemConfig {
-    pub data_directory: PathBuf,
-    pub cache_directory: PathBuf,
+use super::macros::config_struct;
+
+config_struct! {
+    /// The file system config.
+    #[derive(Debug, Deserialize, Serialize, PartialEq, Eq)]
+    #[serde(deny_unknown_fields, default)]
+    pub struct FileSystemConfig {
+        #[comment_out = true]
+        /// The data directory.
+        pub data_directory: PathBuf,
+
+        #[comment_out = true]
+        /// The cache directory.
+        pub cache_directory: PathBuf,
+    }
 }
 
 impl Default for FileSystemConfig {