docs: streamline Python docs with unified guides and clearer examples

- Refresh overview with the core “fast, correct, safe, simple” example plus clearer file/tag/roundtrip sections.
- Replace Usage with a “YAML in 2 Minutes” guide covering a full first example, collections, scalars, and an end-to-end sample.
- Expand Tags into an advanced guide on handlers, mapping keys, streams, anchors, tag directives, and core tags, using concise assertions and named args.
- Tidy API examples to assert full round-trips.
- Update MkDocs nav to group the two guides under Guides.

Author: t-kalinowski

docs/api.md

@@ -46,19 +46,18 @@ from yaml12 import Yaml, format_yaml, parse_yaml
 
 # Tagged scalar
 text = format_yaml({"env": Yaml("prod", "!env")})
-assert "!env" in text
-assert isinstance(parse_yaml(text)["env"], Yaml)
+env = parse_yaml(text)["env"]
+assert isinstance(env, Yaml) and env.tag == "!env" and env.value == "prod"
 
 # Collection key
 data = {Yaml(["a", "b"]): "val"}
 out = format_yaml(data)
-assert parse_yaml(out)[Yaml(["a", "b"])] == "val"
+assert parse_yaml(out) == data
 
 # Tagged collection key
 data = {Yaml(["a", "b"], "!pair"): "val"}
 out = format_yaml(data)
-key = next(iter(parse_yaml(out)))
-assert isinstance(key, Yaml) and key.tag == "!pair" and key.value == ["a", "b"]
+assert parse_yaml(out) == data
 ```
 
 ## _dbg_yaml(text)

docs/index.md

@@ -1,6 +1,6 @@
 # yaml12
 
-`yaml12` exposes the Rust-based `saphyr` YAML 1.2 parser and emitter to Python through a small, function-first API. The bindings keep conversions lean, support multi-document streams, and materialize tagged nodes or unhashable mapping keys as a single lightweight `Yaml` dataclass (also exported as `Tagged` and `MappingKey`); otherwise you just use plain Python types.
+`yaml12` exposes the Rust-based `saphyr` YAML 1.2 parser and emitter to Python through a small, function-first API. The bindings keep conversions lean, support multi-document streams, and materialize tagged nodes or unhashable mapping keys as a single lightweight `Yaml` dataclass; otherwise you just use plain Python types.
 
 - Parse YAML text or files into familiar Python types with `parse_yaml` and `read_yaml`; handlers apply to both values and keys.
 - Serialize Python values back to YAML with `format_yaml` or write directly to disk/stdout with `write_yaml`, including non-core tags.
@@ -22,27 +22,109 @@ pip install -e . --no-build-isolation
 ```python
 from yaml12 import parse_yaml, format_yaml
 
-doc = parse_yaml("server:\\n  port: 8000\\n  debug: true")
-assert doc == {"server": {"port": 8000, "debug": True}}
+yaml_text = """
+title: A modern YAML parser and emitter written in Rust
+properties: [fast, correct, safe, simple]
+features:
+  tags: preserve
+  streams: multi
+"""
+
+doc = parse_yaml(yaml_text)
+
+assert doc == {
+    "title": "A modern YAML parser and emitter written in Rust",
+    "properties": ["fast", "correct", "safe", "simple"],
+    "features": {"tags": "preserve", "streams": "multi"},
+}
 
 text = format_yaml(doc)
 print(text)
-# server:
-#   port: 8000
-#   debug: true
+# title: A modern YAML parser and emitter written in Rust
+# properties:
+#   - fast
+#   - correct
+#   - safe
+#   - simple
+# features:
+#   tags: preserve
+#   streams: multi
+```
+
+### Reading and writing files
+
+```python
+from yaml12 import read_yaml, write_yaml
+
+value_out = {"alpha": 1, "nested": [True, None]}
+
+write_yaml(value_out, "my.yaml")
+value_in = read_yaml("my.yaml")
+
+assert value_in == value_out
+
+# Multi-document streams
+docs_out = [{"foo": 1}, {"bar": [2, None]}]
+
+write_yaml(docs_out, "my-multi.yaml", multi=True)
+docs_in = read_yaml("my-multi.yaml", multi=True)
+
+assert docs_in == docs_out
+```
+
+### Tag handlers
+
+Handlers let you opt into custom behaviour for tagged nodes while keeping the default parser strict and safe.
+
+```python
+from yaml12 import parse_yaml
+
+yaml_text = """
+- !upper [rust, python]
+- !expr 6 * 7
+"""
+
+handlers = {
+    "!expr": lambda value: eval(value),
+    "!upper": str.upper,
+}
+
+doc = parse_yaml(yaml_text, handlers=handlers)
+assert doc == [["RUST", "PYTHON"], 42]
 ```
 
-Multi-document streams are just as simple:
+### Formatting and round-tripping
 
 ```python
-docs = parse_yaml(["first: 1", "second: 2"], multi=True)
-assert docs == [{"first": 1}, {"second": 2}]
+from yaml12 import Yaml, format_yaml, parse_yaml
+
+obj = {
+    "seq": [1, 2],
+    "map": {"key": "value"},
+    "tagged": Yaml("1 + 1", "!expr"),
+}
+
+yaml_text = format_yaml(obj)
+print(yaml_text)
+# seq:
+#   - 1
+#   - 2
+# map:
+#   key: value
+# tagged: !expr 1 + 1
+
+parsed = parse_yaml(yaml_text)
+assert parsed == {
+    "seq": [1, 2],
+    "map": {"key": "value"},
+    "tagged": Yaml("1 + 1", "!expr"),
+}
 ```
 
 ## Where to go next
 
-- Learn how to parse and emit YAML in more detail in [Usage](usage.md).
-- See how to work with custom tags and handlers in [Custom Tags](tags.md).
+- Learn YAML essentials in [YAML in 2 Minutes](usage.md).
+- Explore tags, anchors, and advanced features in [Tags, Anchors, and Advanced YAML](tags.md).
 - Scan the callable surface in [API Reference](api.md).
 
 ## Build or serve the docs locally