From 6c8bb32b7e5862e92c26f571bd3aec01609d8df6 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 13 Sep 2022 15:25:23 +0200 Subject: [PATCH] Add chapter on describing config types Signed-off-by: Matthias Beyer --- src/SUMMARY.md | 1 + src/in-depth/render-configuration.md | 46 ++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 src/in-depth/render-configuration.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index f861e6c..849d479 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -17,4 +17,5 @@ - [Communicating with humans](./in-depth/human-communication.md) - [Communicating with machines](./in-depth/machine-communication.md) - [Rendering documentation for your CLI apps](./in-depth/docs.md) + - [Rendering documentation for your Configuration](./in-depth/render-configuration.md) - [Resources](./resources/README.md) diff --git a/src/in-depth/render-configuration.md b/src/in-depth/render-configuration.md new file mode 100644 index 0000000..a3ba0ab --- /dev/null +++ b/src/in-depth/render-configuration.md @@ -0,0 +1,46 @@ +# Rendering documentation for your Configuration + +If your application offers extensive configuration options, you may want to +render these for the conveniance of the user. + +You could render them straight to the terminal, so that a user can "ask" your +app what configuration it provides: + +```commandline +myapp print-config-options +``` + +Using the [type_description crate](https://crates.io/crates/type_description) +you can annotate your configuration struct(s) and let Rust do the magic: + +```rust,ignore +use type_description::AsTypeDescription; +use type_description::TypeDescription; +use type_description::TypeKind; +use type_description::Sign; + +/// A configuration +#[derive(TypeDescription)] +struct Config { + /// The bind address + addr: std::net::SocketAddr, + + /// The Port + port: u16, +} +``` + +The derive macro implements the `AsTypeDescription` on your `Config` type and +uses the comments as descriptions. + +The `type_description` crate also implements the `AsTypeDescription` trait for +the most common types for configuration from the standard library, such as +numbers, `bool`, `String`, but also `Option`, `Vec` or `HashMap`. + +You can then use `Config::as_type_description()` to get the description for your +`Config` type. + +You can render this information to a web-page, pdf, or simply to text and +print it on the commandline (render functionality +[within the type_description crate is currently unreleased](https://github.com/TheNeikos/type_description/blob/master/src/render.rs#L70)). +