Add docs generation. (#109)

Author: tychedelia

.github/workflows/docs.yml

@@ -0,0 +1,68 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - uses: ./.github/actions/setup
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - uses: astral-sh/setup-uv@v6
+
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            target/
+          key: ${{ runner.os }}-cargo-docs-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-docs-
+            ${{ runner.os }}-cargo-
+
+      - name: Build extension and generate stubs
+        run: |
+          cd crates/processing_pyo3
+          uv run maturin develop --release
+          cd ../..
+          cargo run --release -p generate_stubs
+
+      - name: Build docs
+        run: uv run --project crates/processing_pyo3 --group docs mkdocs build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,4 +1,6 @@
 /target/
+/site/
 crates/processing_ffi/include/
+crates/processing_pyo3/mewnala/*.pyi
 .DS_Store
 .ipynb_checkpoints/

crates/processing_pyo3/pyproject.toml

@@ -35,6 +35,11 @@ Issues = "https://github.com/processing/libprocessing/issues"
 
 [dependency-groups]
 dev = ["maturin>=1.10,<2.0"]
+docs = [
+    "mkdocs-material>=9.6",
+    "mkdocstrings[python]>=0.29",
+    "mkdocs-gen-files>=0.5",
+]
 
 [tool.maturin]
 manifest-path = "Cargo.toml"

crates/processing_pyo3/uv.lock

@@ -403,8 +403,13 @@ impl ErasedRenderAsset for CustomMaterial {
         let bind_group_layout =
             BindGroupLayoutDescriptor::new("custom_material_bind_group", &layout_entries);
 
-        let bindings =
-            reflection.create_bindings(3, &source_asset.shader, render_device, gpu_images, gpu_buffers);
+        let bindings = reflection.create_bindings(
+            3,
+            &source_asset.shader,
+            render_device,
+            gpu_images,
+            gpu_buffers,
+        );
 
         let unprepared = UnpreparedBindGroup {
             bindings: BindingResources(bindings),

crates/processing_render/src/material/custom.rs

@@ -0,0 +1,22 @@
+from pathlib import Path
+
+import mkdocs_gen_files
+
+readme = Path("crates/processing_pyo3/README.md").read_text(encoding="utf-8")
+with mkdocs_gen_files.open("index.md", "w") as f:
+    f.write(readme)
+
+modules = {
+    "reference/index.md": ("API Reference", "mewnala", {"show_submodules": False}),
+    "reference/math.md": ("mewnala.math", "mewnala.math", {}),
+    "reference/color.md": ("mewnala.color", "mewnala.color", {}),
+}
+
+for path, (title, module, options) in modules.items():
+    with mkdocs_gen_files.open(path, "w") as f:
+        f.write(f"# {title}\n\n")
+        if options:
+            opts = "\n".join(f"      {k}: {v}" for k, v in options.items())
+            f.write(f"::: {module}\n    options:\n{opts}\n")
+        else:
+            f.write(f"::: {module}\n")

docs/gen_ref_pages.py

@@ -20,6 +20,12 @@ py-jupyter file: py-build
 py-ipython: py-build
     cd crates/processing_pyo3; ipython
 
+docs-serve: py-stubs
+    uv run --project crates/processing_pyo3 --group docs mkdocs serve
+
+docs-build: py-stubs
+    uv run --project crates/processing_pyo3 --group docs mkdocs build
+
 wasm-build:
     wasm-pack build crates/processing_wasm --target web --out-dir ../../target/wasm
 

justfile

@@ -0,0 +1,65 @@
+site_name: mewnala
+site_description: Mewnala, I choose you!
+site_url: https://processing.github.io/libprocessing/
+repo_url: https://github.com/processing/libprocessing
+repo_name: processing/libprocessing
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: deep purple
+      accent: pink
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: deep purple
+      accent: pink
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - content.code.copy
+    - navigation.sections
+    - navigation.expand
+    - search.highlight
+
+plugins:
+  - search
+  - gen-files:
+      scripts:
+        - docs/gen_ref_pages.py
+  - mkdocstrings:
+      handlers:
+        python:
+          paths:
+            - crates/processing_pyo3
+          options:
+            allow_inspection: false
+            show_source: false
+            show_root_heading: true
+            show_root_full_path: false
+            members_order: alphabetical
+            docstring_style: google
+            show_if_no_docstring: true
+            filters:
+              - "!^_"
+
+nav:
+  - Home: index.md
+  - API Reference:
+      - Overview: reference/index.md
+      - Math: reference/math.md
+      - Color: reference/color.md
+  - Design:
+      - Principles: principles.md
+      - Internal API: api.md
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - pymdownx.inlinehilite
+  - admonition
+  - pymdownx.details

mkdocs.yml

@@ -41,7 +41,10 @@ fn main() {
 
     eprintln!("Introspecting: {}", cdylib_path.display());
 
-    let module = introspect_cdylib(&cdylib_path, "mewnala").expect("Failed to introspect cdylib");
+    let mut module =
+        introspect_cdylib(&cdylib_path, "mewnala").expect("Failed to introspect cdylib");
+
+    module.incomplete = false;
 
     let stubs = module_stub_files(&module);