improve NUON documentation (#12717)

# Description
this PR
- moves the documentation from `lib.rs` to `README.md` while still
including it in the lib file, so that both the [crates.io
page](https://crates.io/crates/nuon) and the
[documentation](https://docs.rs/nuon/latest/nuon/) show the top-level
doc
- mention that comments are allowed in NUON
- add a JSON-NUON example
- put back the formatting of NOTE blocks in the doc

# User-Facing Changes

# Tests + Formatting

# After Submitting

crates/nuon/README.md

@@ -0,0 +1,35 @@
+Support for the NUON format.
+
+The NUON format is a superset of JSON designed to fit the feel of Nushell.
+Some of its extra features are
+- trailing commas are allowed
+- commas are optional in lists
+- quotes are not required around keys or any _bare_ string that do not contain spaces
+- comments are allowed, though not preserved when using [`from_nuon`]
+
+## Example
+below is some data in the JSON format
+```json
+{
+    "name": "Some One",
+    "birth": "1970-01-01",
+    "stats": [
+      2544729499973429198,
+      687051042647753531,
+      6702443901704799912
+    ]
+}
+```
+
+and an equivalent piece of data written in NUON
+```nuon
+{
+    name: "Some One",       # the name of the person
+    birth: "1970-01-01",    # their date of birth
+    stats: [                # some dummy "stats" about them
+      2544729499973429198,
+      687051042647753531,
+      6702443901704799912, # note the trailing comma here...
+    ], # and here
+} # wait, are these comments in a JSON-like document?!?!
+```

crates/nuon/src/from.rs

@@ -7,6 +7,8 @@ use std::sync::Arc;
 
 /// convert a raw string representation of NUON data to an actual Nushell [`Value`]
 ///
+// WARNING: please leave the following two trailing spaces, they matter for the documentation
+// formatting
 /// > **Note**  
 /// > [`Span`] can be passed to [`from_nuon`] if there is context available to the caller, e.g. when
 /// > using this function in a command implementation such as

crates/nuon/src/lib.rs

@@ -1,9 +1,4 @@
-//! Support for the NUON format.
+#![doc = include_str!("../README.md")]
-//!
-//! The NUON format is a superset of JSON designed to fit the feel of Nushell.
-//! Some of its extra features are
-//! - trailing commas are allowed
-//! - quotes are not required around keys
 mod from;
 mod to;
 

crates/nuon/src/to.rs

@@ -39,6 +39,8 @@ pub enum ToStyle {
 
 /// convert an actual Nushell [`Value`] to a raw string representation of the NUON data
 ///
+// WARNING: please leave the following two trailing spaces, they matter for the documentation
+// formatting
 /// > **Note**  
 /// > a [`Span`] can be passed to [`to_nuon`] if there is context available to the caller, e.g. when
 /// > using this function in a command implementation such as [`to nuon`](https://www.nushell.sh/commands/docs/to_nuon.html).