fix(docs): Enhance documentation and configuration for numerous widgets

- Updated mkdocs.yml to include new Templating section and improved theme settings with color scheme toggles.
- Added new dependencies for mkdocs-material, mkdocs-gen-files, mkdocs-section-index, and mkdocs-literate-nav in pyproject.toml.
- Expanded process_task.md, state_model.md, and widgets.md to include new widget documentation with show_root_heading options.
- Modified render_template function in templating module to accept AnyWidget for keyword arguments.

These changes improve the overall documentation structure and enhance the user experience with better theming and widget integration.

docs/README.md

@@ -1,5 +1,8 @@
 # Numerous Widgets
 
+[![pypi badge](https://img.shields.io/pypi/v/numerous-widgets)](https://pypi.python.org/pypi/numerous-widgets)
+[![Release workflow badge](https://github.com/numerous-com/numerous-widgets/actions/workflows/release.yml/badge.svg)](https://github.com/numerous-com/numerous-widgets/actions/workflows/release.yml) 
+
 Welcome to the widgets project.
 
 The project consists of widgets for use in Python apps, as well as python libraries for app state management and long running tasks.
@@ -138,10 +141,4 @@ To run the docs, from the `docs` directory, run:
 mkdocs serve
 ```
 
-This will start a development server and open a browser window with the docs.
-
-## To Do
-
-- [ ] Setup pre-commit hooks for ruff, mypy and pytest
-- [ ] Add tests for the widgets
-- [ ] Finalize a basic widget set
+This will start a development server and open a browser window with the docs.

docs/process_task.md

@@ -39,4 +39,15 @@ This example shows how to:
 3. Create a startup function
 4. Connect everything with `process_task_control`
 
+## ::: widgets.ProcessTask
+    options:
+        show_root_heading: true
+
+## ::: widgets.SubprocessTask
+    options:
+        show_root_heading: true
+
+## ::: widgets.process_task_control
+    options:
+        show_root_heading: true
 

docs/state_model.md

@@ -41,4 +41,10 @@ model.apply_values(new_model)
 # number_widget.val = 20
 ```
 
+## ::: widgets.state.StateModel
+    options:
+        show_root_heading: true
 
+## ::: widgets.state.number_field
+    options:
+        show_root_heading: true

docs/templating.md

@@ -0,0 +1,5 @@
+# Templating
+
+## ::: widgets.templating.render_template
+    options:
+        show_root_heading: true

docs/widgets.md

@@ -2,78 +2,74 @@
 
 The widgets are available in the `widgets` module.
 
-## ::: numerous.widgets.Number
+## ::: widgets.Number
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.CheckBox
+## ::: widgets.CheckBox
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.DropDown
+## ::: widgets.DropDown
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.Button
+## ::: widgets.Button
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.ProgressBar
+## ::: widgets.ProgressBar
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.Tabs
+## ::: widgets.Tabs
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.render_tab_content
+## ::: widgets.container
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.container
+## ::: widgets.Timer
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.Timer
+## ::: widgets.Task
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.Task
+## ::: widgets.MapSelector
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.MapSelector
+## ::: widgets.Slider
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.Slider
+## ::: widgets.RadioButtons
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.RadioButtons
+## ::: widgets.String
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.StringInput
+## ::: widgets.MarkdownDisplay
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.MarkdownDisplay
+## ::: widgets.Accordion
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.Accordion
+## ::: widgets.Chat
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.Chat
+## ::: widgets.Table
     options:
         show_root_heading: true
 
-## ::: numerous.widgets.Table
-    options:
-        show_root_heading: true
-
-## ::: numerous.widgets.Task
+## ::: widgets.Task
     options:
         show_root_heading: true

mkdocs.yml

@@ -9,20 +9,57 @@ nav:
     - Widgets: widgets.md
     - Process Task: process_task.md
     - State Model: state_model.md
+    - Templating: templating.md
+
+theme:
+  name: material
+  logo: logo.svg
+  favicon: favicon.png
+  features:
+      - content.code.copy
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default 
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
 
-theme: readthedocs
 plugins:
   - search
+  - gen-files:
+      scripts:
+        - scripts/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
   - mkdocstrings:
       default_handler: "python"
       handlers:
         python:
           setup_commands:
-            - "import sys; sys.path.insert(0, '.')"
-          paths: [.]
+            - "import sys; sys.path.insert(0, './python/src/numerous')"
+          paths: [./python/src/numerous]
           import:
             - https://docs.python.org/3/objects.inv
           rendering:
             show_source: true
             show_full_signature: true
             show_root_heading: true
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences

pyproject.toml

@@ -38,6 +38,10 @@ dev = [
     "mkdocstrings==0.26.2",
     "mkdocstrings-python==1.12.2",
     "mkdocs_snippet_plugin==1.0.2",
+    "mkdocs-material==9.5.46",
+    "mkdocs-gen-files==0.5.0",
+    "mkdocs-section-index==0.3.9",
+    "mkdocs-literate-nav==0.6.1",
     # for testing related to frameworks
     "marimo",
     "panel"

python/src/numerous/widgets/templating/__init__.py

@@ -1,13 +1,14 @@
 """Templating is for rendering Jinja2 templates."""
 
-from typing import IO, Any
+from typing import IO
 
+from anywidget import AnyWidget
 from jinja2 import Template
 
 
-def render_template(template: str | IO[str], **kwargs: dict[str, Any]) -> str:
+def render_template(template: str | IO[str], **kwargs: dict[str, AnyWidget]) -> str:
     """
-    Render a Jinja2 template with processed keyword arguments.
+    Render a Jinja2 template with marimo widgets.
 
     Args:
         template: Either a template string or a file-like object containing the template

scripts/gen_ref_pages.py

@@ -0,0 +1,44 @@
+# noqa:INP001
+"""
+Generate the API reference pages.
+
+See: https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
+"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent
+src = root / "python" / "src" / "numerous"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if any(part.startswith("_") and not part.startswith("__") for part in parts):
+        # skip internal packages and modules
+        continue
+    elif parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        print("::: " + identifier, file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())