Merge pull request #36 from bcdev/forman-x-contrib_docs

forman · web-flow · commit 1d9e58bd60df · 2024-11-14T15:18:22.000+01:00
More documentation
diff --git a/chartlets.py/chartlets/__init__.py b/chartlets.py/chartlets/__init__.py
@@ -1,4 +1,5 @@
 from .callback import Callback
+from .channel import Channel
 from .channel import Input
 from .channel import Output
 from .channel import State
diff --git a/chartlets.py/chartlets/channel.py b/chartlets.py/chartlets/channel.py
@@ -42,8 +42,25 @@ def no_trigger(self):
 
 
 class Input(Channel):
-    """An input value read from component state.
-    A component state change may trigger callback invocation.
+    """Describes the source of a parameter value for the user-provided
+    layout and callback functions.
+    `Input` instances are used as arguments passed to the
+    `layout` and `callback` decorators.
+
+    An `Input` describes from which property in which state a parameter
+    value is read. According state changes trigger callback invocation.
+
+    Args:
+        id:
+            Value of a component's "id" property.
+            Used only if `source` is `"component"`.
+        property:
+            Name of the property of a component or state.
+            To address properties in nested objects or arrays
+            use a dot (`.`) to separate property names and array
+            indexes.
+        source: One of `"component"` (the default), `"container"`,
+            or `"app"`.
     """
 
     # noinspection PyShadowingBuiltins
@@ -58,8 +75,26 @@ def __init__(
 
 
 class State(Input):
-    """An input value read from component state.
-    Does not trigger callback invocation.
+    """Describes the source of a parameter value for the user-provided
+    layout and callback functions.
+    `State` instances are used as arguments passed to the
+    `layout` and `callback` decorators.
+
+    Just like an `Input`, a `State` describes from which property in which state
+    a parameter value is read, but according state changes
+    will **not*Ü* trigger callback invocation.
+
+    Args:
+        id:
+            Value of a component's "id" property.
+            Used only if `source` is `"component"`.
+        property:
+            Name of the property of a component or state.
+            To address properties in nested objects or arrays
+            use a dot (`.`) to separate property names and array
+            indexes.
+        source: One of `"component"` (the default), `"container"`,
+            or `"app"`.
     """
 
     # noinspection PyShadowingBuiltins
@@ -73,7 +108,26 @@ def __init__(
 
 
 class Output(Channel):
-    """Callback output."""
+    """Describes the target of a value returned from a user-provided
+    callback function.
+    `Output` instances are used as arguments passed to the
+    `callback` decorators.
+
+    An `Output` describes which property in which state should be
+    updated from the returned callback value.
+
+    Args:
+        id:
+            Value of a component's "id" property.
+            Used only if `source` is `"component"`.
+        property:
+            Name of the property of a component or state.
+            To address properties in nested objects or arrays
+            use a dot (`.`) to separate property names and array
+            indexes.
+        target: One of `"component"` (the default), `"container"`,
+            or `"app"`.
+    """
 
     # noinspection PyShadowingBuiltins
     def __init__(
diff --git a/chartlets.py/chartlets/component.py b/chartlets.py/chartlets/component.py
@@ -8,6 +8,7 @@ class Component(ABC):
     """Base class for components.
     Provides the common attributes that apply to all components.
     """
+
     # Common HTML properties
     id: str | None = None
     """HTML `id` property. Required for referring to this component."""
diff --git a/chartlets.py/chartlets/contribution.py b/chartlets.py/chartlets/contribution.py
@@ -18,6 +18,7 @@ class Contribution(ABC):
         name: A name that should be unique within an extension.
         initial_state: contribution specific attribute values.
     """
+
     # noinspection PyShadowingBuiltins
     def __init__(self, name: str, **initial_state):
         self.name = name
@@ -27,8 +28,13 @@ def __init__(self, name: str, **initial_state):
         self.callbacks: list[Callback] = []
 
     def to_dict(self) -> dict[str, Any]:
-        """Convert this contribution into a
-        JSON serializable dictionary.
+        """Convert this contribution into a JSON serializable dictionary.
+
+        May be overridden by subclasses to allow for specific
+        JSON serialization.
+
+        Returns:
+            A JSON serializable dictionary.
         """
         d = dict(name=self.name)
         if self.initial_state is not None:
@@ -41,10 +47,13 @@ def to_dict(self) -> dict[str, Any]:
             d.update(callbacks=[cb.to_dict() for cb in self.callbacks])
         return d
 
-    def layout(self, *args) -> Callable:
-        """A decorator for a user-provided function that
+    def layout(self, *args) -> Callable[[Callable], Callable]:
+        """Provides a decorator for a user-provided function that
         returns the initial user interface layout.
 
+        The layout decorator should only be used once for
+        given contribution instance.
+
         The decorated function must return an instance of
         a `chartlets.Component`, usually a `chartlets.components.Box`
         that arranges other components in some layout.
@@ -56,16 +65,18 @@ def layout(self, *args) -> Callable:
         called `ctx`.
 
         Other parameters of the decorated function are user-defined
-        and must have a corresponding `chartlets.Input` argument
-        in the `layout` decorator in the same order.
+        and must have a corresponding `chartlets.Input` or
+        `chartlets.State` arguments in the `layout` decorator in the
+        same order.
 
         Args:
-            args: Instances of the `chartlets.Input` class that
+            args:
+                `chartlets.Input` or `chartlets.State` objects that
                 define the source of the value for the corresponding
                 parameter of the decorated function. Optional.
 
         Returns:
-             The decorated, user-provided function.
+             The decorator.
         """
 
         def decorator(function: Callable) -> Callable:
@@ -77,7 +88,39 @@ def decorator(function: Callable) -> Callable:
         return decorator
 
     def callback(self, *args: Channel) -> Callable[[Callable], Callable]:
-        """Decorator."""
+        """Provide a decorator for a user-provided callback function.
+
+        Callback functions are event handlers that react
+        to events fired by the host application state or by events
+        fired by related components provided by this contribution's
+        layout.
+
+        The first parameter of the decorated function must be a
+        positional argument. It provides an application-specific
+        context that is used to allow for access server-side
+        configuration and resources. The parameter should be
+        called `ctx`.
+
+        Other parameters of the decorated function are user-defined
+        and must have a corresponding `chartlets.Input` argument
+        in the `layout` decorator in the same order.
+
+        The return value of the decorated function is used to change
+        the component or the application state as described by its
+        `Output` argument passed to the decorator. If more than out
+        output is specified, the function is supposed to return a tuple
+        of values with the same number of items in the order given
+        by the `Output` arguments passed to the decorator.
+
+        Args:
+            args:
+                `chartlets.Input`, `chartlets.State`, and `Output` objects that
+                define sources and targets for the parameters passed to the
+                callback function and the returned from the callback function.
+
+        Returns:
+             The decorated, user-provided function.
+        """
 
         def decorator(function: Callable) -> Callable:
             self.callbacks.append(
@@ -88,6 +131,3 @@ def decorator(function: Callable) -> Callable:
             return function
 
         return decorator
-
-    def __str__(self):
-        return self.name
diff --git a/chartlets.py/chartlets/controllers/callback.py b/chartlets.py/chartlets/controllers/callback.py
@@ -5,20 +5,23 @@
 
 
 # POST /chartlets/callback
-def get_callback_results(ext_ctx: ExtensionContext | None, data: dict[str, Any]):
-    """Generate the response for `POST /chartlets/callback`.
+def get_callback_results(
+    ext_ctx: ExtensionContext | None, data: dict[str, Any]
+) -> Response:
+    """Generate the response for the endpoint `POST /chartlets/callback`.
 
     Args:
-        ext_ctx: Extension context.
+        ext_ctx: Extension context. If `None`,
+            the function returns a 404 error response.
         data: A dictionary deserialized from a request JSON body
-            that may contain a key `callbackRequests` of type `list`.
+            that should contain a key `callbackRequests` of type `list`.
     Returns:
-        A JSON-serializable list.
+        A `Response` object.
+        On success, the response is a list of state-change requests
+        grouped by contributions.
     """
     if ext_ctx is None:
-        return Response.failed(
-            404, f"no contributions configured"
-        )
+        return Response.failed(404, f"no contributions configured")
 
     # TODO: validate data
     callback_requests: list[dict] = data.get("callbackRequests") or []
diff --git a/chartlets.py/chartlets/controllers/contributions.py b/chartlets.py/chartlets/controllers/contributions.py
@@ -3,11 +3,18 @@
 
 
 def get_contributions(ext_ctx: ExtensionContext | None) -> Response:
-    """Generate the response for `GET /chartlets/contributions`."""
+    """Generate the response for the endpoint `GET /chartlets/contributions`.
+
+    Args:
+        ext_ctx: Extension context. If `None`,
+            the function returns a 404 error response.
+    Returns:
+        A `Response` object.
+        On success, the response is a dictionary that represents
+        a JSON-serialized component tree.
+    """
     if ext_ctx is None:
-        return Response.failed(
-            404, f"no contributions configured"
-        )
+        return Response.failed(404, f"no contributions configured")
 
     extensions = ext_ctx.extensions
     contributions = ext_ctx.contributions
diff --git a/chartlets.py/chartlets/controllers/layout.py b/chartlets.py/chartlets/controllers/layout.py
@@ -10,22 +10,23 @@ def get_layout(
     contrib_index: int,
     data: dict[str, Any],
 ) -> Response:
-    """Generate the response for
+    """Generate the response for the endpoint
     `POST /chartlets/layout/{contrib_point_name}/{contrib_index}`.
 
     Args:
-        ext_ctx: Extension context.
+        ext_ctx: Extension context. If `None`,
+            the function returns a 404 error response.
         contrib_point_name: Contribution point name.
         contrib_index: Contribution index.
         data: A dictionary deserialized from a request JSON body
             that may contain a key `inputValues` of type `list`.
     Returns:
-        A JSON-serializable dictionary.
+        A `Response` object.
+        On success, the response is a dictionary that represents
+        a JSON-serialized component tree.
     """
     if ext_ctx is None:
-        return Response.failed(
-            404, f"no contributions configured"
-        )
+        return Response.failed(404, f"no contributions configured")
 
     # TODO: validate data
     input_values = data.get("inputValues") or []
diff --git a/docs/api/components.md b/docs/api/components.md
@@ -0,0 +1,31 @@
+# Components API
+
+The Chartlets component API is used by both application contributors 
+and providers:
+
+- Application contributors use the concrete component classes to create a 
+  contribution's user interface and to output updated components or parts of 
+  it from their callback implementations.
+- Application providers use the abstract base classes `Component` and 
+  `Container` to implement new specific components.
+
+
+## Specific Components
+
+::: chartlets.components.Box
+
+::: chartlets.components.Button
+
+::: chartlets.components.Checkbox
+
+::: chartlets.components.Dropdown
+
+::: chartlets.components.Plot
+
+::: chartlets.components.Typography
+
+## Base classes
+
+::: chartlets.Component
+
+::: chartlets.Container
diff --git a/docs/api/contribution.md b/docs/api/contribution.md
@@ -0,0 +1,21 @@
+# Contribution API
+
+The Chartlets contribution API is used by both application providers 
+and contributors:
+
+- Application providers implement specific contributions for their application
+  using `Contribution` as a base class.
+- Application contributors use the instantiate and parameterize the specific 
+  contributions and implement the functions to create the contributions'
+  user interface (layout) and their event handlers (callbacks).
+
+
+::: chartlets.Contribution
+
+::: chartlets.Input
+
+::: chartlets.State
+
+::: chartlets.Output
+
+::: chartlets.Channel
diff --git a/docs/api/controllers.md b/docs/api/controllers.md
@@ -0,0 +1,25 @@
+# Controllers API
+
+The Chartlets controllers API is used by application providers only.
+As an application contributor you do not need to care about it.
+
+A controller implements the logic of a specific Chartlets web API endpoint.
+It is used to efficiently implement the Chartlets web API using any 
+web framework such as FastAPI, Flask or Tornado.
+
+Controllers are imported from the `chartlets.components` module, for example:
+
+```python
+from chartlets.controllers import get_layout
+```
+
+
+::: chartlets.controllers.get_contributions
+
+::: chartlets.controllers.get_layout
+
+::: chartlets.controllers.get_callback_results
+
+::: chartlets.ExtensionContext
+
+::: chartlets.Response
diff --git a/docs/api/extension.md b/docs/api/extension.md
@@ -0,0 +1,3 @@
+# Extension API
+
+::: chartlets.Extension
diff --git a/docs/components.md b/docs/components.md
diff --git a/mkdocs.yml b/mkdocs.yml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`from .callback import Callback`
	`2`	`+from .channel import Channel`
`2`	`3`	`from .channel import Input`
`3`	`4`	`from .channel import Output`
`4`	`5`	`from .channel import State`