Merge pull request #1424 from sfauvel/sfa/command-line-doc

Generate documentation on module command lines

Author: sfauvel

Cargo.lock

@@ -12,6 +12,8 @@ members = [
   "mithril-client-cli",
   "mithril-client-wasm",
   "mithril-common",
+  "mithril-doc",
+  "mithril-doc-derive",
   "mithril-persistence",
   "mithril-relay",
   "mithril-signer",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mithrildemo"
-version = "0.1.29"
+version = "0.1.30"
 authors = { workspace = true }
 edition = { workspace = true }
 documentation = { workspace = true }
@@ -15,6 +15,7 @@ clap = { version = "4.4.18", features = ["derive"] }
 hex = "0.4.3"
 log = "0.4.20"
 mithril-common = { path = "../../mithril-common", features = ["fs"] }
+mithril-doc = { path = "../../mithril-doc" }
 rand_chacha = "0.3.1"
 rand_core = "0.6.4"
 serde = { version = "1.0.196", features = ["derive"] }

demo/protocol-demo/Cargo.toml

@@ -316,7 +316,7 @@ impl Demonstrator {
             })
             .collect::<Vec<Vec<u8>>>();
         Self {
-            config: *config,
+            config: config.clone(),
             parties,
             verifier: None,
             messages,
@@ -495,6 +495,7 @@ mod tests {
     fn default_config() -> crate::Config {
         let protocol_parameters = setup_protocol_parameters();
         crate::Config {
+            command: None,
             m: protocol_parameters.m,
             k: protocol_parameters.k,
             phi_f: protocol_parameters.phi_f,

demo/protocol-demo/src/demonstrator.rs

@@ -2,13 +2,18 @@ mod demonstrator;
 mod types;
 
 use crate::demonstrator::{Demonstrator, ProtocolDemonstrator};
-use clap::Parser;
+use clap::{CommandFactory, Parser, Subcommand};
+use mithril_doc::GenerateDocCommands;
 use rand_chacha::ChaCha20Rng;
 use rand_core::SeedableRng;
 
 /// Simple demonstration of the Mithril protocol
-#[derive(Parser, Debug, PartialEq, Clone, Copy)]
+#[derive(Parser, Debug, PartialEq)]
 pub struct Config {
+    /// Available commands
+    #[command(subcommand)]
+    command: Option<DemoCommands>,
+
     /// Security parameter, upper bound on indices
     #[clap(short, long, default_value_t = 200)]
     m: u64,
@@ -30,9 +35,29 @@ pub struct Config {
     nmessages: usize,
 }
 
+impl Clone for Config {
+    fn clone(&self) -> Self {
+        Config {
+            command: None,
+            ..*self
+        }
+    }
+}
+
+#[derive(Subcommand, Debug, PartialEq)]
+enum DemoCommands {
+    #[clap(alias("doc"), hide(true))]
+    GenerateDoc(GenerateDocCommands),
+}
+
 fn main() {
     let config = Config::parse();
 
+    if let Some(DemoCommands::GenerateDoc(cmd)) = &config.command {
+        cmd.execute(&mut Config::command()).unwrap();
+        return;
+    }
+
     println!(">> Launch Mithril protocol demonstrator with configuration: \n{config:#?}");
 
     //////////////////////

demo/protocol-demo/src/main.rs

@@ -1,6 +1,6 @@
 [package]
 name = "mithril-aggregator"
-version = "0.4.38"
+version = "0.4.39"
 description = "A Mithril Aggregator server"
 authors = { workspace = true }
 edition = { workspace = true }
@@ -19,6 +19,7 @@ config = "0.13.4"
 flate2 = "1.0.28"
 hex = "0.4.3"
 mithril-common = { path = "../mithril-common", features = ["full"] }
+mithril-doc = { path = "../mithril-doc" }
 mithril-persistence = { path = "../mithril-persistence" }
 openssl = { version = "0.10.63", features = ["vendored"], optional = true }
 openssl-probe = { version = "0.1.5", optional = true }

mithril-aggregator/Cargo.toml

@@ -3,14 +3,17 @@ mod genesis_command;
 mod serve_command;
 mod tools_command;
 
-use clap::{Parser, Subcommand};
+use anyhow::anyhow;
+use clap::{CommandFactory, Parser, Subcommand};
 use config::{builder::DefaultState, ConfigBuilder, Map, Source, Value, ValueKind};
 use mithril_common::StdResult;
+use mithril_doc::{Documenter, DocumenterDefault, StructDoc};
 use slog::Level;
 use slog_scope::debug;
 use std::path::PathBuf;
 
-use crate::DefaultConfiguration;
+use crate::{Configuration, DefaultConfiguration};
+use mithril_doc::GenerateDocCommands;
 
 /// Main command selector
 #[derive(Debug, Clone, Subcommand)]
@@ -19,6 +22,8 @@ pub enum MainCommand {
     Era(era_command::EraCommand),
     Serve(serve_command::ServeCommand),
     Tools(tools_command::ToolsCommand),
+    #[clap(alias("doc"), hide(true))]
+    GenerateDoc(GenerateDocCommands),
 }
 
 impl MainCommand {
@@ -28,12 +33,17 @@ impl MainCommand {
             Self::Era(cmd) => cmd.execute(config_builder).await,
             Self::Serve(cmd) => cmd.execute(config_builder).await,
             Self::Tools(cmd) => cmd.execute(config_builder).await,
+            Self::GenerateDoc(cmd) => {
+                let config_infos = vec![Configuration::extract(), DefaultConfiguration::extract()];
+                cmd.execute_with_configurations(&mut MainOpts::command(), &config_infos)
+                    .map_err(|message| anyhow!(message))
+            }
         }
     }
 }
 
 /// Mithril Aggregator Node
-#[derive(Parser, Debug, Clone)]
+#[derive(Documenter, Parser, Debug, Clone)]
 #[command(version)]
 pub struct MainOpts {
     /// application main command
@@ -46,6 +56,7 @@ pub struct MainOpts {
 
     /// Verbosity level
     #[clap(short, long, action = clap::ArgAction::Count)]
+    #[example = "Parsed from the number of occurrences: `-v` for `Warning`, `-vv` for `Info`, `-vvv` for `Debug` and `-vvvv` for `Trace`"]
     pub verbose: u8,
 
     /// Directory of the Cardano node files

mithril-aggregator/src/commands/mod.rs

@@ -3,6 +3,7 @@ use config::{ConfigError, Map, Source, Value, ValueKind};
 use mithril_common::chain_observer::ChainObserverType;
 use mithril_common::crypto_helper::ProtocolGenesisSigner;
 use mithril_common::era::adapters::EraReaderAdapterType;
+use mithril_doc::{Documenter, DocumenterDefault, StructDoc};
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
 use std::str::FromStr;
@@ -39,16 +40,18 @@ impl FromStr for ExecutionEnvironment {
 }
 
 /// Aggregator configuration
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, Documenter)]
 pub struct Configuration {
     /// What kind of runtime environment the configuration is meant to.
     pub environment: ExecutionEnvironment,
 
     /// Cardano CLI tool path
+    #[example = "`cardano-cli`"]
     pub cardano_cli_path: PathBuf,
 
     /// Path of the socket used by the Cardano CLI tool
     /// to communicate with the Cardano node
+    #[example = "`/tmp/cardano.sock`"]
     pub cardano_node_socket_path: PathBuf,
 
     /// Cardano node version.
@@ -61,18 +64,22 @@ pub struct Configuration {
     /// Cardano Network Magic number
     ///
     /// useful for TestNet & DevNet
+    #[example = "`1097911063` or `42`"]
     pub network_magic: Option<u64>,
 
     /// Cardano network
+    #[example = "`testnet` or `mainnet` or `devnet`"]
     pub network: String,
 
     /// Cardano chain observer type
     pub chain_observer_type: ChainObserverType,
 
     /// Protocol parameters
+    #[example = "`{ k: 5, m: 100, phi_f: 0.65 }`"]
     pub protocol_parameters: ProtocolParameters,
 
     /// Type of snapshot uploader to use
+    #[example = "`gcp` or `local`"]
     pub snapshot_uploader_type: SnapshotUploaderType,
 
     /// Bucket name where the snapshots are stored if snapshot_uploader_type is Gcp
@@ -88,6 +95,7 @@ pub struct Configuration {
     pub server_port: u16,
 
     /// Run Interval is the interval between two runtime cycles in ms
+    #[example = "`60000`"]
     pub run_interval: u64,
 
     /// Directory of the Cardano node store.
@@ -97,6 +105,7 @@ pub struct Configuration {
     pub snapshot_directory: PathBuf,
 
     /// Directory to store aggregator data (Certificates, Snapshots, Protocol Parameters, ...)
+    #[example = "`./mithril-aggregator/stores`"]
     pub data_stores_directory: PathBuf,
 
     /// Genesis verification key
@@ -120,14 +129,17 @@ pub struct Configuration {
     /// Era reader adapter parameters
     pub era_reader_adapter_params: Option<String>,
 
-    /// Signed entity types parameters (discriminants names in an ordered comma separated list).
+    /// Signed entity types parameters (discriminants names in an ordered comma separated list).    
+    #[example = "`MithrilStakeDistribution,CardanoImmutableFilesFull,CardanoStakeDistribution`"]
     pub signed_entity_types: Option<String>,
 
     /// Compression algorithm used for the snapshot archive artifacts.
+    #[example = "`gzip` or `zstandard`"]
     pub snapshot_compression_algorithm: CompressionAlgorithm,
 
     /// Specific parameters when [snapshot_compression_algorithm][Self::snapshot_compression_algorithm]
     /// is set to [zstandard][CompressionAlgorithm::Zstandard].
+    #[example = "`{ level: 9, number_of_workers: 4 }`"]
     pub zstandard_parameters: Option<ZstandardCompressionParameters>,
 
     /// Url to CExplorer list of pools to import as signer in the database.
@@ -284,9 +296,8 @@ impl Configuration {
         Ok(signed_entity_types)
     }
 }
-
 /// Default configuration with all the default values for configurations.
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, DocumenterDefault)]
 pub struct DefaultConfiguration {
     /// Execution environment
     pub environment: ExecutionEnvironment,
@@ -304,6 +315,7 @@ pub struct DefaultConfiguration {
     pub snapshot_directory: String,
 
     /// Type of snapshot store to use
+    #[example = "`gcp` or `local`"]
     pub snapshot_store_type: String,
 
     /// Type of snapshot uploader to use