Docs

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches:
+      - master  # Adjust if your main branch is named differently
+  workflow_dispatch:  # Allow manual trigger
+
+permissions:
+  contents: write  # Needed to push to gh-pages
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for proper git info
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests (including doctests)
+        run: |
+          pytest --doctest-modules plotille/ -v
+
+      - name: Generate documentation
+        run: |
+          python scripts/generate_docs.py
+
+      - name: Build MkDocs site
+        run: |
+          mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          cname: plotille.tammo.io

.gitignore

@@ -10,6 +10,23 @@ build/
 *.so
 *.c
 *.html
+!docs/overrides/*.html
+
+# Brython runtime files (generated, should be installed via make docs-setup)
+docs/brython.js
+docs/brython_stdlib.js
+docs/unicode.txt
+docs/README.txt
+docs/demo.html
+docs/ansi_up.js
+# Documentation build artifacts
+docs/Lib/
+docs/assets/example-outputs/
+docs/cookbook/
+docs/index.md
+docs/stylesheets/ansi-colors.css
+
+
 *.pyc
 __pycache__/
 dist/
@@ -19,3 +36,7 @@ Pipfile.lock
 cov_html/
 coverage.xml
 pip-wheel-metadata/
+site/
+.mypy_cache/
+.ruff_cache/
+.uv/

Makefile

@@ -1,4 +1,4 @@
-.PHONY: style tests install
+.PHONY: style tests install docs docs-setup docs-serve
 
 fmt:
 	uv run --locked ruff format .
@@ -17,3 +17,27 @@ tests:
 
 install:
 	uv install
+
+docs-copy-plotille:
+	@echo "Copy plotille to docs folder"
+	@rm -rf docs/Lib
+	@mkdir -p docs/Lib/site-packages/plotille
+	@cp plotille/*.py docs/Lib/site-packages/plotille/
+
+docs-brython:
+	@echo "Installing Brython runtime..."
+	@rm -f docs/brython.js docs/brython_stdlib.js docs/unicode.txt docs/demo.html docs/README.txt docs/index.html
+	@echo "Y" | uv run brython-cli install --install-dir docs
+	@rm -f docs/demo.html docs/README.txt docs/index.html
+	@echo "✓ Brython installed to docs/"
+
+docs/ansi_up.js:
+	@echo "Downloading AnsiUp library..."
+	@curl -sL -o docs/ansi_up.js https://unpkg.com/ansi_up@6.0.2/ansi_up.js
+	@echo "✓ AnsiUp downloaded to docs/"
+
+docs: docs-copy-plotille docs/ansi_up.js docs-brython
+	uv run python docs/generate_docs.py
+
+docs-serve: docs
+	uv run mkdocs serve --dev-addr 127.0.0.1:8000

README.md

@@ -34,6 +34,13 @@ If you are still using python 2.7, please use plotille v4 or before. With v5 I a
 
 ## Documentation
 
+📚 **Full documentation available at [plotille.tammo.io](https://plotille.tammo.io)**
+
+Features:
+- **Interactive examples** - Edit and run code in your browser
+- **Complete API reference** - Auto-generated from source
+- **Cookbook** - Examples organized by complexity
+
 ```python
 In [1]: import plotille
 In [2]: import numpy as np

docs/api/canvas.md

@@ -0,0 +1,17 @@
+# Canvas
+
+Low-level canvas for direct drawing.
+
+::: plotille.Canvas
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - __init__
+        - point
+        - line
+        - rect
+        - text
+        - braille_image
+        - image
+        - plot

docs/api/figure.md

@@ -0,0 +1,21 @@
+# Figure
+
+The Figure class for composing complex visualizations.
+
+::: plotille.Figure
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - __init__
+        - plot
+        - scatter
+        - histogram
+        - text
+        - axvline
+        - axhline
+        - axvspan
+        - axhspan
+        - imgshow
+        - show
+        - clear

docs/api/index.md

@@ -0,0 +1,20 @@
+# API Reference
+
+Complete API documentation for plotille.
+
+## High-Level Functions
+
+Quick plotting functions for simple use cases.
+
+- [Plotting Functions](plotting.md) - `plot()`, `scatter()`, `histogram()`
+- [Figure Class](figure.md) - Compose complex multi-plot visualizations
+
+## Core Components
+
+- [Canvas](canvas.md) - Low-level drawing primitives
+- [Colors](colors.md) - Color handling and themes
+
+## Utilities
+
+- [Input Formatting](formatting.md) - Data preprocessing
+- [Data Types](datatypes.md) - Internal data structures

docs/api/plotting.md

@@ -0,0 +1,31 @@
+# Plotting Functions
+
+High-level plotting functions for quick visualizations.
+
+## plot
+
+::: plotille.plot
+    options:
+      show_root_heading: true
+      show_source: true
+
+## scatter
+
+::: plotille.scatter
+    options:
+      show_root_heading: true
+      show_source: true
+
+## hist
+
+::: plotille.hist
+    options:
+      show_root_heading: true
+      show_source: true
+
+## histogram
+
+::: plotille.histogram
+    options:
+      show_root_heading: true
+      show_source: true