Component docs (#35)

* Initial docs

* Update chartlets.js/README.md

Co-authored-by: b-yogesh <[email protected]>

* Update chartlets.py/README.md

Co-authored-by: b-yogesh <[email protected]>

* Update docs/components.md

Co-authored-by: b-yogesh <[email protected]>

* Update docs/index.md

Co-authored-by: b-yogesh <[email protected]>

* Update docs/demo.md

Co-authored-by: b-yogesh <[email protected]>

* Update docs/usage.md

Co-authored-by: b-yogesh <[email protected]>

* Initial component docs

* Updated component docs

* Update

* Update chartlets.py/chartlets/component.py

Co-authored-by: b-yogesh <[email protected]>

* Update chartlets.py/chartlets/component.py

Co-authored-by: b-yogesh <[email protected]>

* Update chartlets.py/chartlets/components/box.py

Co-authored-by: b-yogesh <[email protected]>

* Update chartlets.py/chartlets/components/typography.py

Co-authored-by: b-yogesh <[email protected]>

---------

Co-authored-by: b-yogesh <[email protected]>

Author: forman

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Brockmann Consult Development
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,7 +1,21 @@
 # Chartlets
 
-`chartlets` is a framework for server-configured web-UI contributions.
+Chartlets is a software framework that allows websites developed with
+React to be extended by server-side UI contributions programmed in Python 
+or other programming languages. 
 
 It comprises a [Python backend package](chartlets.py/README.md)
 and a [JavaScript/React frontend package](chartlets.js/README.md).
 
+Please see the [Documentation]() for more information.
+
+## Features
+
+- Enhance your React web application by UI-contributions programmed in Python
+- Enhance your (Python) web API to serve server-side UI-contributions.
+- Uses [Material UI](https://mui.com/material-ui/) components and 
+  [Vega-Lite](https://vega.github.io/vega-lite/) charts.
+
+## License
+
+[MIT](https://github.com/bcdev/chartlets/blob/master/LICENSE)

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
+    """Label used by many specific components. Optional """
+
     children: list["Component"] | None = None
+    """Children used by many specific components. Optional """
 
     @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 to layout the box and its child components.
+    """
+
+    component: str | None = None
+    """The component to be used, e.g., `div` or `span`."""

chartlets.py/chartlets/components/button.py

@@ -5,4 +5,8 @@
 
 @dataclass(frozen=True)
 class Button(Component):
+    """Buttons allow users to take actions, and make choices,
+    with a single tap."""
+
     text: str | None = None
+    """The button text."""

chartlets.py/chartlets/components/checkbox.py

@@ -5,5 +5,11 @@
 
 @dataclass(frozen=True)
 class Checkbox(Component):
+    """Checkboxes allow the user to select one or more items from a set.
+    They can be used to turn an option on or off."""
+
     value: bool | None = None
+    """The checkbox value."""
+
     label: str = ""
+    """The checkbox label."""

chartlets.py/chartlets/components/dropdown.py

@@ -5,4 +5,8 @@
 
 @dataclass(frozen=True)
 class Dropdown(Component):
+    """Dropdown components are used for collecting user provided
+    information from a list of options."""
+
     options: list[tuple[str, str | int | float]] = field(default_factory=list)
+    """The options given as a list of (label, value) pairs."""

chartlets.py/chartlets/components/plot.py

@@ -8,7 +8,12 @@
 
 @dataclass(frozen=True)
 class Plot(Component):
+    """The plot component is a container for a
+    [Vega Altair](https://altair-viz.github.io/) chart."""
+
     chart: alt.Chart | None = None
+    """The Vega Altair 
+    [chart object](https://altair-viz.github.io/user_guide/generated/toplevel/altair.Chart.html)."""
 
     def to_dict(self) -> dict[str, Any]:
         d = super().to_dict()

chartlets.py/chartlets/components/typography.py

@@ -5,4 +5,14 @@
 
 @dataclass(frozen=True)
 class Typography(Component):
+    """Use typography to present your design and content as clearly
+    and efficiently as possible."""
+
     text: str | None = None
+    """Text to be displayed. Optional"""
+
+    color: str | None = None
+    """The color of the component."""
+
+    variant: str | None = None
+    """Applies the theme typography styles."""

chartlets.py/pyproject.toml

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