Initial component docs

Author: forman

chartlets.py/chartlets/component.py

@@ -5,16 +5,30 @@
 
 @dataclass(frozen=True)
 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."""
+
     name: str | None = None
+    """HTML `name` property. Optional."""
+
     value: bool | int | float | str | None = None
+    """HTML `value` property. Required for specific components."""
+
     style: dict[str, Any] | None = None
+    """HTML `style` property. Optional."""
+
     # We may add more here later
     #
     # Special non-HTML properties
     label: str | None = None
+    """Optional label used by many specific components."""
+
     children: list["Component"] | None = None
+    """Optional children used by many specific components."""
 
     @property
     def type(self):

chartlets.py/chartlets/components/box.py

@@ -5,4 +5,11 @@
 
 @dataclass(frozen=True)
 class Box(Container):
-    pass
+    """The Box component is a generic container for grouping other components.
+    It's a fundamental building block. Think of it as an HTML `<div>` element.
+
+    Use the `style` attribute how to layout the box and its child components.
+    """
+
+    component: str | None = None
+    """The component to be used, e.g., `div` or `span`."""

chartlets.py/pyproject.toml

@@ -60,7 +60,9 @@ dev = [
 ]
 doc = [
   "mkdocs",
-  "mkdocs-material"
+  "mkdocs-material",
+  "mkdocstrings",
+  "mkdocstrings-python"
 ]
 demo = [
   "pyaml",

docs/components.md

@@ -7,9 +7,16 @@ module, e.g.
 from chartlets.components import Checkbox
 ```
 
-- Box
-- Button
-- Checkbox
-- Dropdown
-- Plot
-- Typography
+::: chartlets.components.Box
+
+::: chartlets.components.Button
+
+::: chartlets.components.Checkbox
+
+::: chartlets.components.Dropdown
+
+::: chartlets.components.Typography
+
+
+::: chartlets.Component
+

docs/usage.md

@@ -38,7 +38,7 @@ Extension.add_contrib_point("panels", Panel)
 
 ### 3. Load the extensions
 
-Load the extensions that augments your application.
+Load the extensions that augment your application.
 
 As an example, see [`server.py` of the demo](chartlets.py/chartlets/demo/server.py):
 

mkdocs.yml

@@ -1,5 +1,17 @@
 site_name: chartlets
 
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [ "chartlets.py" ]
+          options:
+            show_source: false
+            show_if_no_docstring: false
+            show_root_heading: true
+            heading_level: 2
+
 nav:
   - Home: index.md
   - Demo: demo.md
@@ -44,3 +56,4 @@ validation:
   absolute_links: warn
   unrecognized_links: warn
   anchors: warn
+