chore: improve CLI line breaks and markdown-handling (#1736)

During #1720 I noticed that there are a few places in the CLI where a
few more line breaks and handling markdown better could help
readability.

Yes, this adds the `unstable-markdown` feature of clap, but given that
removal would only impact the CLI-Formatting, I think here the risk is
okay.
Tracking issue:
- clap-rs/clap#5900


Hidden rationale:
I have one place in #1720 where making it readable without markdown
formatting is nearly impossible

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: CommanderStorm

Cargo.lock

@@ -37,7 +37,7 @@ approx = "0.5.1"
 async-trait = "0.1"
 bit-set = "0.8"
 brotli = ">=5, <8"
-clap = { version = "4", features = ["derive"] }
+clap = { version = "4", features = ["derive", "unstable-markdown"] }
 criterion = { version = "0.5", features = ["async_futures", "async_tokio", "html_reports"] }
 ctor = "0.4.1"
 dashmap = { version =  "6.1.0", features = ["serde", "inline", "rayon"] }

Cargo.toml

@@ -1,9 +1,11 @@
 ## Command-line Interface
 
-You can configure Martin using command-line interface. See `martin --help` or `cargo run -- --help` for more
-information.
+You can configure Martin using command-line interface.
+See `martin --help` or `cargo run -- --help` for more information:
 
 ```text
+Blazing fast and lightweight tile server with PostGIS, MBTiles, and PMTiles support
+
 Usage: martin [OPTIONS] [CONNECTION]...
 
 Arguments:
@@ -15,7 +17,8 @@ Options:
           Path to config file. If set, no tile source-related parameters are allowed
 
       --save-config <SAVE_CONFIG>
-          Save resulting config to a file or use "-" to print to stdout. By default, only print if sources are auto-detected
+          Save resulting config to a file or use "-" to print to stdout.
+          By default, only print if sources are auto-detected
 
   -C, --cache-size <CACHE_SIZE>
           Main cache size (in MB)
@@ -33,24 +36,30 @@ Options:
           The socket address to bind. [DEFAULT: 0.0.0.0:3000]
 
       --base-path <BASE_PATH>
-          Set TileJSON URL path prefix. This overrides the default of respecting the X-Rewrite-URL header.
-          Only modifies the JSON (TileJSON) returned, martins' API-URLs remain unchanged. If you need to rewrite URLs, please use a reverse proxy.
-          Must begin with a `/`.
-          Examples: `/`, `/tiles`
+          Set TileJSON URL path prefix.
+
+          This overrides the default of respecting the X-Rewrite-URL header.
+          Only modifies the JSON (TileJSON) returned, martins' API-URLs remain unchanged.
+          If you need to rewrite URLs, please use a reverse proxy.
+          Must begin with a /.
+
+          Examples: /, /tiles
 
   -W, --workers <WORKERS>
           Number of web server workers
 
       --preferred-encoding <PREFERRED_ENCODING>
-          Martin server preferred tile encoding. If the client accepts multiple compression formats, and the tile source is not pre-compressed, which compression should be used. `gzip` is faster, but `brotli` is smaller, and may be faster with caching.  Defaults to gzip
+          Martin server preferred tile encoding. [DEFAULT: gzip]
+
+          If the client accepts multiple compression formats, and the tile source is not pre-compressed, which compression should be used. gzip is faster, but brotli is smaller, and may be faster with caching.
 
           [possible values: brotli, gzip]
 
   -u, --webui <WEB_UI>
-          Control Martin web UI.  Disabled by default
+          Control Martin web UI. [DEFAULT: disabled]
 
           Possible values:
-          - disable:        Disable Web UI interface. This is the default, but once implemented, the default will be enabled for localhost
+          - disable:        Disable Web UI interface. This is the default, but once implemented, the default will be enabled for localhost.
           - enable-for-all: Enable Web UI interface on all connections
 
   -b, --auto-bounds <AUTO_BOUNDS>
@@ -78,4 +87,6 @@ Options:
 
   -V, --version
           Print version
+
+Use RUST_LOG environment variable to control logging level, e.g. RUST_LOG=debug or RUST_LOG=martin=debug. See https://docs.rs/env_logger/latest/env_logger/index.html#enabling-logging for more information.
 ```

docs/src/run-with-cli.md

@@ -56,7 +56,7 @@ pub struct MetaArgs {
     /// **Deprecated** Scan for new sources on sources list requests
     #[arg(short, long, hide = true)]
     pub watch: bool,
-    /// Connection strings, e.g. postgres://... or /path/to/files
+    /// Connection strings, e.g. `postgres://...` or `/path/to/files`
     pub connection: Vec<String>,
 }
 

martin/src/args/root.rs

@@ -11,19 +11,26 @@ pub struct SrvArgs {
     pub keep_alive: Option<u64>,
     #[arg(help = format!("The socket address to bind. [DEFAULT: {LISTEN_ADDRESSES_DEFAULT}]"), short, long)]
     pub listen_addresses: Option<String>,
-    /// Set TileJSON URL path prefix. This overrides the default of respecting the X-Rewrite-URL header.
-    /// Only modifies the JSON (TileJSON) returned, martins' API-URLs remain unchanged. If you need to rewrite URLs, please use a reverse proxy.
+    /// Set TileJSON URL path prefix.
+    ///
+    /// This overrides the default of respecting the X-Rewrite-URL header.
+    /// Only modifies the JSON (TileJSON) returned, martins' API-URLs remain unchanged.
+    /// If you need to rewrite URLs, please use a reverse proxy.
     /// Must begin with a `/`.
+    ///
     /// Examples: `/`, `/tiles`
     #[arg(long)]
     pub base_path: Option<String>,
     /// Number of web server workers
     #[arg(short = 'W', long)]
     pub workers: Option<usize>,
-    /// Martin server preferred tile encoding. If the client accepts multiple compression formats, and the tile source is not pre-compressed, which compression should be used. `gzip` is faster, but `brotli` is smaller, and may be faster with caching.  Defaults to gzip.
+    /// Martin server preferred tile encoding. [DEFAULT: gzip]
+    ///
+    /// If the client accepts multiple compression formats, and the tile source is not pre-compressed, which compression should be used.
+    /// `gzip` is faster, but `brotli` is smaller, and may be faster with caching.
     #[arg(long)]
     pub preferred_encoding: Option<PreferredEncoding>,
-    /// Control Martin web UI.  Disabled by default.
+    /// Control Martin web UI. [DEFAULT: disabled]
     #[arg(short = 'u', long = "webui")]
     #[cfg(feature = "webui")]
     pub web_ui: Option<WebUiMode>,
@@ -33,7 +40,7 @@ pub struct SrvArgs {
 #[derive(PartialEq, Eq, Debug, Clone, Copy, Default, Serialize, Deserialize, ValueEnum)]
 #[serde(rename_all = "lowercase")]
 pub enum WebUiMode {
-    /// Disable Web UI interface. This is the default, but once implemented, the default will be enabled for localhost.
+    /// Disable Web UI interface. ***This is the default, but once implemented, the default will be enabled for localhost.***
     #[default]
     #[serde(alias = "false")]
     Disable,

martin/src/args/srv.rs

@@ -60,7 +60,7 @@ pub struct CopyArgs {
     /// Path to the mbtiles file to copy to.
     #[arg(short, long)]
     pub output_file: PathBuf,
-    /// Output format of the new destination file. Ignored if the file exists. Defaults to 'normalized'.
+    /// Output format of the new destination file. Ignored if the file exists. [DEFAULT: normalized]
     #[arg(
         long = "mbtiles-type",
         alias = "dst-type",
@@ -72,6 +72,7 @@ pub struct CopyArgs {
     #[arg(long)]
     pub url_query: Option<String>,
     /// Optional accepted encoding parameter as if the browser sent it in the HTTP request.
+    ///
     /// If set to multiple values like `gzip,br`, martin-cp will use the first encoding,
     /// or re-encode if the tile is already encoded and that encoding is not listed.
     /// Use `identity` to disable compression. Ignored for non-encodable tiles like PNG and JPEG.
@@ -103,7 +104,7 @@ pub struct CopyArgs {
     /// Skip generating a global hash for mbtiles validation. By default, `martin-cp` will compute and update `agg_tiles_hash` metadata value.
     #[arg(long)]
     pub skip_agg_tiles_hash: bool,
-    /// Set additional metadata values. Must be set as "key=value" pairs. Can be specified multiple times.
+    /// Set additional metadata values. Must be set as `"key=value"` pairs. Can be specified multiple times.
     #[arg(long, value_name="KEY=VALUE", value_parser = parse_key_value)]
     pub set_meta: Vec<(String, String)>,
 }