feat: docs

Author: iamgp

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Needed for git-revision-date-localized plugin
+      
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      
+      - name: Install documentation dependencies
+        run: uv sync --group docs
+      
+      - name: Build documentation
+        run: uv run --group docs mkdocs build --clean
+      
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -27,3 +27,6 @@ __pycache__/
 *.egg
 
 .pypirc
+
+# MkDocs generated site
+site/

docs/README.md

@@ -0,0 +1,50 @@
+# Dashkit Documentation
+
+Welcome to the Dashkit documentation! This directory contains comprehensive guides and API references for using and maintaining dash-dashkit.
+
+## 📚 Documentation Structure
+
+### For Users
+- **[API Reference](api/README.md)** - Complete component API documentation
+- **[Quick Start Guide](guides/quickstart.md)** - Get up and running quickly
+
+### For Maintainers  
+- **[Development Setup](internals/development.md)** - Local development environment
+- **[Architecture Overview](internals/architecture.md)** - Understanding the codebase
+
+## 🚀 Getting Started
+
+If you're new to Dashkit, start with the [Quick Start Guide](guides/quickstart.md).
+
+## 📖 Building Documentation
+
+This documentation is built with MkDocs and Material for MkDocs theme.
+
+### Local Development
+
+```bash
+# Install documentation dependencies
+uv run task docs-install
+
+# Serve documentation locally with hot reload
+uv run task docs-serve
+
+# Build static documentation
+uv run task docs-build
+```
+
+### Deployment
+
+Documentation is automatically deployed to GitHub Pages when changes are pushed to the main branch.
+
+```bash
+# Manual deployment to GitHub Pages
+uv run task docs-deploy
+```
+
+## 📖 Additional Resources
+
+- [Main README](../README.md) - Project overview and basic setup
+- [CHANGELOG](../CHANGELOG.md) - Version history and changes  
+- [PyPI Package](https://pypi.org/project/dash-dashkit/) - Official package
+- [GitHub Repository](https://github.com/iamgp/dash_dashkit) - Source code and issues

docs/api/README.md

@@ -0,0 +1,91 @@
+# API Reference
+
+Complete reference for all Dashkit components and functions.
+
+## Core Components
+
+### Layout Components
+- **[create_layout](components/layout.md)** - Main application layout with sidebar and header
+- **[create_sidebar](components/sidebar.md)** - Configurable sidebar navigation  
+- **[create_header](components/header.md)** - Two-tier header with actions and search
+
+### UI Components  
+- **[Table](components/table.md)** - Modern data tables with Handsontable integration
+- **[Buttons](components/buttons.md)** - Primary and secondary button components
+- **[Cards](components/cards.md)** - Card containers for content organization
+- **[MarkdownReport](components/markdown.md)** - Markdown content rendering
+
+### Chart Components (Optional)
+- **[AreaChart](components/charts.md#areachart)** - Area chart visualization
+- **[BarChart](components/charts.md#barchart)** - Bar chart visualization  
+- **[ChartContainer](components/charts.md#chartcontainer)** - Chart wrapper component
+
+## Setup & Configuration
+
+### Application Setup
+- **[setup_app](setup.md#setup_app)** - Configure Dash app with Dashkit styling
+
+### Theme Management
+- **[ThemeManager](theming.md)** - Theme switching and persistence
+
+## Installation Options
+
+```bash
+# Core components only
+pip install dash-dashkit
+
+# With table support  
+pip install dash-dashkit[table]
+
+# With chart support
+pip install dash-dashkit[charts]
+
+# With contribution graphs
+pip install dash-dashkit[kiboui]
+
+# Everything included
+pip install dash-dashkit[all]
+```
+
+## Import Structure
+
+```python
+# Core imports
+from dashkit import create_layout, setup_app
+from dashkit import Table, PrimaryButton, SecondaryButton
+from dashkit import Card, MetricCard, ChartCard, MarkdownReport
+
+# Optional chart imports (requires dashkit_shadcn)
+from dashkit import AreaChart, BarChart, ChartContainer
+
+# Direct component imports
+from dashkit_table import DashkitTable
+from dashkit_kiboui import ContributionGraph
+from dashkit_shadcn import AreaChart as ShadcnAreaChart
+```
+
+## Quick Example
+
+```python
+from dash import Dash, html
+import dashkit
+
+app = Dash(__name__)
+dashkit.setup_app(app)
+
+data = [{"name": "Alice", "score": 10}, {"name": "Bob", "score": 20}]
+columns = [{"data": "name", "title": "Name"}, {"data": "score", "title": "Score"}]
+
+app.layout = dashkit.create_layout(
+    content=html.Div([
+        html.H3("Dashboard"),
+        dashkit.Table(id="table", data=data, columns=columns, height=300),
+        dashkit.PrimaryButton("Add Row", icon="plus")
+    ]),
+    sidebar_config={"brand_name": "My App"},
+    header_config={"page_title": "Dashboard"}
+)
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```

docs/api/components/buttons.md

@@ -0,0 +1,3 @@
+# Buttons
+
+::: dashkit.buttons

docs/api/components/cards.md

@@ -0,0 +1,3 @@
+# Cards
+
+::: dashkit.card

docs/api/components/charts.md

@@ -0,0 +1,3 @@
+# Charts
+
+::: dashkit.charts

docs/api/components/header.md

@@ -0,0 +1,3 @@
+# Header
+
+::: dashkit.header

docs/api/components/layout.md

@@ -0,0 +1,3 @@
+# Layout
+
+::: dashkit.layout

docs/api/components/markdown.md

@@ -0,0 +1,3 @@
+# Markdown Report
+
+::: dashkit.markdown_report