Generate the readme from doc comments

Author: jan-auer

README.md

@@ -1,12 +1,14 @@
 # dynfmt - Dynamic Formatting in Rust
 
-`dynfmt` provides several implementations for formats that implement a subset of
-the [`std::fmt`] facilities. Parsing of the format string and arguments checks
-are performed at runtime. There is also the option to implement new formats.
+A crate for formatting strings dynamically.
 
-The public API is exposed via the [`Format`] trait, which contains formatting
-helper functions and lower-level utilities to interface with format strings. See
-the Features section for a list of provided implementations.
+`dynfmt` provides several implementations for formats that implement a subset of the
+[`std::fmt`] facilities. Parsing of the format string and arguments checks are performed at
+runtime. There is also the option to implement new formats.
+
+The public API is exposed via the [`Format`] trait, which contains formatting helper functions
+and lower-level utilities to interface with format strings. See the Features section for a list
+of provided implementations.
 
 ## Usage
 
@@ -17,7 +19,60 @@ let formatted = NoopFormat.format("hello, world", &["unused"]);
 assert_eq!("hello, world", formatted.expect("formatting failed"));
 ```
 
-See the [Documentation](https://docs.rs/dynfmt) for more information.
+See the [`Format`] trait for more methods.
+
+## Features
+
+This crate ships with a set of features that either activate formatting capabilities or new
+format implementations:
+
+ - `json` **(default)**: Implements the serialization of complex structures via JSON. Certain
+   formats, such as Python, also have a _representation_ format (`%r`) that makes use of this
+   feature, if enabled. Without this feature, such values will cause an error.
+ - `python`: Implements the `printf`-like format that python 2 used for formatting strings. See
+   [`PythonFormat`] for more information.
+ - `curly`: A simple format string syntax using curly braces for arguments. Similar to .NET and
+   Rust, but much less capable. See [`SimpleCurlyFormat`] for mor information.
+
+## Extensibility
+
+Implement the [`Format`] trait to create a new format. The only required method is `iter_args`,
+which must return an iterator over [`ArgumentSpec`] structs. Based on the capabilities of the
+format, the specs can be parameterized with formatting parameters.
+
+```rust
+use std::str::MatchIndices;
+use dynfmt::{ArgumentSpec, Format, Error};
+
+struct HashFormat;
+
+impl<'f> Format<'f> for HashFormat {
+    type Iter = HashIter<'f>;
+
+    fn iter_args(&self, format: &'f str) -> Result<Self::Iter, Error<'f>> {
+        Ok(HashIter(format.match_indices('#')))
+    }
+}
+
+struct HashIter<'f>(MatchIndices<'f, char>);
+
+impl<'f> Iterator for HashIter<'f> {
+    type Item = Result<ArgumentSpec<'f>, Error<'f>>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.0.next().map(|(index, _)| Ok(ArgumentSpec::new(index, index + 1)))
+    }
+}
+
+let formatted = HashFormat.format("hello, #", &["world"]);
+assert_eq!("hello, world", formatted.expect("formatting failed"));
+```
 
 [`std::fmt`]: https://doc.rust-lang.org/stable/std/fmt/
-[`format`]: https://docs.rs/dynfmt/latest/dynfmt/trait.Format.html
+[`serde::Serialize`]: https://docs.rs/serde/latest/serde/trait.Serialize.html
+[`Format`]: https://docs.rs/dynfmt/latest/dynfmt/trait.Format.html
+[`ArgumentSpec`]: https://docs.rs/dynfmt/latest/dynfmt/struct.ArgumentSpec.html
+[`PythonFormat`]: https://docs.rs/dynfmt/latest/dynfmt/python/struct.PythonFormat.html
+[`SimpleCurlyFormat`]: https://docs.rs/dynfmt/latest/dynfmt/curly/struct.SimpleCurlyFormat.html
+
+License: MIT