Initial docs (#31)

* 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]>

* Update docs/index.md

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

---------

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

Author: forman

.gitignore

@@ -1,3 +1,16 @@
+# Logs
+*.log
+
+# Artifacts
+build
+dist
+# npm
+node_modules
+# pip
+*.egg-info
+# mkdocs
+site
+
 # Editor directories and files
 .vscode/*
 !.vscode/extensions.json
@@ -8,3 +21,4 @@
 *.njsproj
 *.sln
 *.sw?
+.idea/

README.md

@@ -4,3 +4,4 @@
 
 It comprises a [Python backend package](chartlets.py/README.md)
 and a [JavaScript/React frontend package](chartlets.js/README.md).
+

chartlets.js/README.md

@@ -1,54 +1,16 @@
 # chartlets 
 
-Chartlets is a JavaScript library that allows configuring server-side widgets
-and plugging them into existing web frontends.
+Chartlets is a software framework that allows websites developed with
+React to be extended by server-side widgets programmed in Python or other
+programming languages. 
 
-_Note, this library is experimental and under development still._
+This is the JavaScript/React library of the framework.
 
-## How it is supposed to work
+For details refer to the [documentation](https://bcdev.github.io/chartlets/).
 
-Users write the widgets in, e.g. Python, and a REST server implements three 
-endpoints to publish the widgets:
+## Run the demo UI
 
-- `GET /contributions`: Called once after application UI starts up.
-  Returns an object whose keys are contribution points (e.g., "panels") 
-  and whose values are arrays of contribution objects.
-- `POST /layout/{contribPoint}/{contribIndex}`:
-  Called once for every contribution when it becomes visible in the UI.
-  Returns the contribution's initial component tree
-- `POST /callback`:
-  Called when users interact with the component tree or on application 
-  state changes. Returns an array of contribution changes where each 
-  contribution change contains an array of actions to be applied to the 
-  component tree.
-
-The following sequence diagram depicts how the library is supposed to 
-work. The top shows the JavaScript frontend that uses this library.
-The bottom shows the lifeline of the backend REST server.
-
-![docs/sequence.png](docs/sequence.png)
-
-## How to run the demo
-
-```bash
-git clone https://github.com/bcdev/chartlets.git
-```
-
-### Run the server
-
-```bash
-cd chartlets/chartlets.py
-conda env create
-conda activate chartlets
-pip install -ve . 
-python -m chartlets.demo.server
-```
-
-### Run the UI
-
-```bash
-cd ../chartlets.js
+``` bash
 npm install
 npm run dev
 ```
-

chartlets.py/README.md

@@ -1,6 +1,12 @@
 # chartlets 
 
-`chartlets` is a Python framework for server-configured web-UI contributions. 
+Chartlets is a software framework that allows websites developed with
+React to be extended by server-side widgets programmed in Python or other
+programming languages. 
+
+This is the Python backend library of the framework.
+
+For details refer to the [documentation](https://bcdev.github.io/chartlets/).
 
 ## Run demo server
 
@@ -9,62 +15,3 @@ mamba env create
 conda activate chartlets
 python -m chartlets.demo.server 
 ```
-
-## How to use the framework
-
-### 1. Implement the possible contributions
-
-Implement the application-specific contributions that users 
-can add to their extensions.
-
-As an example, see [`panel.py` of the demo](chartlets/demo/contribs/panel.py):
-
-```python
-from chartlets import Contribution
-
-
-class Panel(Contribution):
-    """Panel contribution"""
-
-    def __init__(self, name: str, title: str | None = None):
-        super().__init__(name, title=title)
-```
-
-### 2. Define the contributions points
-
-Define the possible contribution points in your application.
-
-As an example, see [`server.py` of the demo](chartlets/demo/server.py):
-
-```python
-from chartlets import Extension
-from chartlets.demo.contribs import Panel
-
-Extension.add_contrib_point("panels", Panel)
-```
-
-### 3. Load the extensions
-
-Load the extensions that augment your application.
-
-As an example, see [`server.py` of the demo](chartlets/demo/server.py):
-
-```python
-from chartlets import ExtensionContext
-
-ext_ctx = ExtensionContext.load(app_ctx, extension_refs)
-```
-
-### 4. Publish the extensions 
-
-Implement the Chartlets API in your application-specific webserver using
-the controller implementations in `chartlets.controllers`. 
-
-As an example, see [`server.py` of the demo](chartlets/demo/server.py).
-
-### 5. Consume the extensions
-
-Use JavaScript package `chartlets` in your frontend to implement the 
-contribution lifecycle in your React application.
-
-As an example, see [the demo application](../chartlets/src/demo).

chartlets.py/pyproject.toml

@@ -54,6 +54,13 @@ dev = [
   "pytest",
   "pytest-cov",
   "requests-mock",
+  "twine",
+  "build",
+  "hatch"
+]
+doc = [
+  "mkdocs",
+  "mkdocs-material"
 ]
 demo = [
   "pyaml",

docs/about.md

@@ -0,0 +1,15 @@
+Given here is a list of the components supported by chartlets.
+
+Using the Python package, they can be imported from the `chartlets.components` 
+module, e.g.
+
+```python
+from chartlets.components import Checkbox
+```
+
+- Box
+- Button
+- Checkbox
+- Dropdown
+- Plot
+- Typography

docs/components.md

@@ -0,0 +1,24 @@
+Chartlets provides a simple demo that serves as a
+reference for the framework usage and testbed for its features.
+
+```bash
+git clone https://github.com/bcdev/chartlets.git
+```
+
+### Run the server
+
+```bash
+cd chartlets/chartlets.py
+conda env create
+conda activate chartlets
+pip install -ve . 
+python -m chartlets.demo.server
+```
+
+### Run the UI
+
+```bash
+cd ../chartlets.js
+npm install
+npm run dev
+```

docs/demo.md

@@ -0,0 +1,28 @@
+# Welcome to Chartlets
+
+Chartlets is a software framework that allows websites developed with
+React to be extended by server-side widgets programmed in Python or other
+programming languages. 
+
+## How it works
+
+Users write the widgets in, e.g. Python, and a REST server implements three 
+endpoints to publish the widgets:
+
+- `GET /contributions`: Called once after application UI starts up.
+  Returns an object whose keys are contribution points (e.g., "panels") 
+  and whose values are arrays of contribution objects.
+- `POST /layout/{contribPoint}/{contribIndex}`:
+  Called once for every contribution when it becomes visible in the UI.
+  Returns the contribution's initial component tree.
+- `POST /callback`:
+  Called when users interact with the component tree or on application 
+  state changes. Returns an array of contribution changes where each 
+  contribution change contains an array of actions to be applied to the 
+  component tree.
+
+The following sequence diagram depicts how the library is supposed to 
+work. The top shows the JavaScript frontend that uses this library.
+The bottom shows the lifeline of the backend REST server.
+
+![images/sequence.png](images/sequence.png)