docs: general docs update, use mkdocs-api-autonav (#367)

* docs: updating docs

* docs: remove containers guide and update references

* display

* add links

* no cover

Author: tlambert03

docs/API/containers.md

@@ -116,131 +116,138 @@ with the new value as the first argument.
 
 There are two (related) APIs for adding events to dataclasses:
 
-1.  Add a [`SignalGroupDescriptor`][psygnal.SignalGroupDescriptor] as a class attribute.
+### 1. Use `SignalGroupDescriptor`
 
-    !!! example
+[`SignalGroupDescriptor`][psygnal.SignalGroupDescriptor] is designed to be used
+as a class attribute on a dataclass-like object, and, when accessed on an
+instance of that class, will return a [`SignalGroup`][psygnal.SignalGroup] with
+signals for each field in the class.
 
-        === "dataclasses"
+!!! example
 
-            ```python
-            from typing import ClassVar
-            from psygnal import SignalGroupDescriptor
-            from dataclasses import dataclass
+    === "dataclasses"
 
-            @dataclass
-            class Person:
-                name: str
-                age: int = 0
-                events: ClassVar[SignalGroupDescriptor] = SignalGroupDescriptor()
-            ```
+        ```python
+        from typing import ClassVar
+        from psygnal import SignalGroupDescriptor
+        from dataclasses import dataclass
 
-        === "pydantic"
+        @dataclass
+        class Person:
+            name: str
+            age: int = 0
+            events: ClassVar[SignalGroupDescriptor] = SignalGroupDescriptor()
+        ```
 
-            ```python
-            from typing import ClassVar
-            from psygnal import SignalGroupDescriptor
-            from pydantic import BaseModel
+    === "pydantic"
 
-            class Person(BaseModel):
-                name: str
-                age: int = 0
-                events: ClassVar[SignalGroupDescriptor] = SignalGroupDescriptor()
-            ```
+        ```python
+        from typing import ClassVar
+        from psygnal import SignalGroupDescriptor
+        from pydantic import BaseModel
 
-            *for a fully evented subclass of pydantic's `BaseModel`, see also
-            [`EventedModel`](./API/model.md)*
+        class Person(BaseModel):
+            name: str
+            age: int = 0
+            events: ClassVar[SignalGroupDescriptor] = SignalGroupDescriptor()
+        ```
 
-        === "msgspec"
+        *for a fully evented subclass of pydantic's `BaseModel`, see also
+        [`EventedModel`](./model.md)*
 
-            ```python
-            from typing import ClassVar
-            from psygnal import SignalGroupDescriptor
-            import msgspec
+    === "msgspec"
 
-            class Person(msgspec.Struct):
-                name: str
-                age: int = 0
-                events: ClassVar[SignalGroupDescriptor] = SignalGroupDescriptor()
-            ```
+        ```python
+        from typing import ClassVar
+        from psygnal import SignalGroupDescriptor
+        import msgspec
 
-        === "attrs"
+        class Person(msgspec.Struct):
+            name: str
+            age: int = 0
+            events: ClassVar[SignalGroupDescriptor] = SignalGroupDescriptor()
+        ```
 
-            ```python
-            from typing import ClassVar
-            from psygnal import SignalGroupDescriptor
-            from attrs import define
+    === "attrs"
 
-            @define
-            class Person:
-                name: str
-                age: int = 0
-                events: ClassVar[SignalGroupDescriptor] = SignalGroupDescriptor()
-            ```
+        ```python
+        from typing import ClassVar
+        from psygnal import SignalGroupDescriptor
+        from attrs import define
 
-2.  Decorate the class with the [`@evented` decorator][psygnal.evented].
+        @define
+        class Person:
+            name: str
+            age: int = 0
+            events: ClassVar[SignalGroupDescriptor] = SignalGroupDescriptor()
+        ```
 
-    > _Under the hood, this just adds the `SignalGroupDescriptor` as a class
-    > attribute named "events" for you, as shown above). Prefer the class
-    > attribute pattern to the decorator when in doubt._
+### 2. Use the `@evented` decorator
 
-    !!! example
+The [`@evented`][psygnal.evented] decorator can be added to any dataclass-like
+class. Under the hood, this just adds the `SignalGroupDescriptor` as a class
+attribute for you (named "events" by default), as shown above. Prefer the class
+attribute pattern to the decorator when in doubt, as it is more explicit and
+leads to better type checking.
 
-        === "dataclasses"
+!!! example
 
-            ```python
-            from psygnal import evented
-            from dataclasses import dataclass
+    === "dataclasses"
 
-            @evented
-            @dataclass
-            class Person:
-                name: str
-                age: int = 0
-            ```
+        ```python
+        from psygnal import evented
+        from dataclasses import dataclass
 
-        === "pydantic"
+        @evented
+        @dataclass
+        class Person:
+            name: str
+            age: int = 0
+        ```
 
-            ```python
-            from psygnal import evented
-            from pydantic import BaseModel
+    === "pydantic"
 
-            @evented
-            class Person(BaseModel):
-                name: str
-                age: int = 0
-            ```
+        ```python
+        from psygnal import evented
+        from pydantic import BaseModel
 
-            *for a fully evented subclass of pydantic's `BaseModel`, see also
-            [`EventedModel`](./API/model.md)*
+        @evented
+        class Person(BaseModel):
+            name: str
+            age: int = 0
+        ```
 
-        === "msgspec"
+        *for a fully evented subclass of pydantic's `BaseModel`, see also
+        [`EventedModel`](./model.md)*
 
-            ```python
-            from psygnal import evented
-            import msgspec
+    === "msgspec"
 
-            @evented
-            class Person(msgspec.Struct):
-                name: str
-                age: int = 0
-            ```
+        ```python
+        from psygnal import evented
+        import msgspec
+
+        @evented
+        class Person(msgspec.Struct):
+            name: str
+            age: int = 0
+        ```
 
-        === "attrs"
+    === "attrs"
+
+        ```python
+        from psygnal import evented
+        from attrs import define
 
-            ```python
-            from psygnal import evented
-            from attrs import define
+        @evented
+        @define
+        class Person:
+            name: str
+            age: int = 0
+        ```
 
-            @evented
-            @define
-            class Person:
-                name: str
-                age: int = 0
-            ```
-
-    !!! tip
-        by default, the `SignalGroup` instance is named `'events'`, but this can be
-        changed by passing a `events_namespace` argument to the `@evented` decorator)
+!!! tip
+    by default, the `SignalGroup` instance is named `'events'`, but this can be
+    changed by passing a `events_namespace` argument to the `@evented` decorator)
 
 Using any of the above, you can now connect callbacks to the change events
 of any field on the object (there will be a signal instance in the `events`
@@ -270,7 +277,7 @@ def on_any_change(info: EmissionInfo):
     print(f"field {info.signal.name!r} changed to {info.args}")
 ```
 
-see the [API documentation](./API/evented.md) for for more details.
+see the [API documentation](reference/psygnal/) for for more details.
 
 ## Type annotating evented dataclasses
 

docs/API/evented.md

@@ -37,7 +37,7 @@ obj.sig.emit(0)
 Here's an example of a standard Python (3.11) stack trace that you
 might see when running this code:
 
-[![standard stack trace](img/stdlib.png)](img/stdlib.png)
+[![standard stack trace](../img/stdlib.png)](../img/stdlib.png)
 
 All the information is there, but you need to ignore all the
 lines that come from psygnal, and focus on the lines that come from your
@@ -62,4 +62,4 @@ attention to the two places in the code that you can do something about:
 1. The line in the callback that caused the error: `print(1 / x)`
 2. The emission of the event that triggered the callback: `obj.sig.emit(0)`
 
-[![rich stack trace](img/rich.png)](img/rich.png)
+[![rich stack trace](../img/rich.png)](../img/rich.png)

docs/API/index.md

@@ -0,0 +1,36 @@
+# Evented Model
+
+This class provides an "evented" version of pydantic's
+[`BaseModel`](https://pydantic-docs.helpmanual.io/usage/models/), that emits a
+signal whenever a field value is changed
+
+This is an alternative to using the lighter-weight [`@evented` dataclass
+decorator](./dataclasses.md). In addition to simply gaining events on all
+fields, the [`EventedModel`][psygnal.EventedModel] provides additional features including
+`property.setters`, and json encoding features.
+
+```python
+from psygnal import EventedModel
+
+class MyModel(EventedModel):
+    x: int = 1
+    y: int = 2
+
+# Create an instance of the model
+model = MyModel()
+
+# Connect to the `x` field's event
+model.events.x.connect(lambda value: print(f"x changed to {value}"))
+
+# Update the `x` field
+model.x = 42  # Prints: "x changed to 42"
+```
+
+In this example:
+
+- The `EventedModel` automatically creates events for each field.
+- You can connect callbacks to these events to respond to changes in field
+  values.
+
+See documentation for the [`EventedModel`][psygnal.EventedModel] class for
+more.