Dev

.github/workflows/deploy_docs.yml

@@ -42,7 +42,8 @@ jobs:
           # Always install sphinx and required extensions
           python -m pip install \
             "sphinx>=7,<9" \
-            sphinx-rtd-theme
+            sphinx-rtd-theme \
+            "brython==3.12.*"
 
           pip install numpy
 

.github/workflows/python-package.yml

@@ -17,7 +17,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v4
@@ -36,7 +36,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install pytest
+        python -m pip install pytest numpy
         python fetch_dependencies.py
         python -m pip install .
     #- name: Setup tmate session

.github/workflows/python-publish.yml

@@ -14,54 +14,31 @@ on:
 
 
 jobs:
-  #build_mac_and_windows:
-  #  name: Build Python Package
-  #  runs-on: ${{ matrix.os }}
-  #  strategy:
-  #    fail-fast: false
-  #    matrix:
-  #      os: [windows-latest, macos-latest]
-  #      python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
-
-  #  steps:
-  #  - uses: actions/checkout@v4
-  #  - name: Set up Python ${{ matrix.python-version }}
-  #    uses: actions/setup-python@v3
-  #    with:
-  #      python-version: ${{ matrix.python-version }}
-  #  - name: Install dependencies
-  #    run: |
-  #      python -m pip install --upgrade pip
-  #      python fetch_dependencies.py
-  #      python -m pip install build
-  #      python -m build
-  #  - name: Store the distribution packages
-  #    uses: actions/upload-artifact@v3
-  #    with:
-  #      name: python-package-distributions
-  #      path: dist/
-  build_wheels:
-    name: Build wheels on ${{ matrix.os }}
+
+  build_native_wheels:
+    name: Build native wheels on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-13, macos-14]
+        os: [ubuntu-latest, windows-latest, macos-15-intel, macos-15]
 
     steps:
       - uses: actions/checkout@v4
 
       # Used to host cibuildwheel
       - uses: actions/setup-python@v5
 
-      - name: Install cibuildwheel
+      - name: Install cibuildwheel and native deps
         run: |
           python -m pip install --upgrade pip
-          python -m pip install cibuildwheel==2.23.3
+          python -m pip install cibuildwheel==3.2.1
           python fetch_dependencies.py
 
-      - name: Build wheels
+      - name: Build native wheels
         env:
           CIBW_SKIP: 'pp* manylinux_i686 musllinux*'
+          VKDISPATCH_BUILD_TARGET: native
+          CIBW_ENVIRONMENT: VKDISPATCH_BUILD_TARGET=native
         run: python -m cibuildwheel --output-dir wheelhouse
 
         # to supply options, put them in 'env', like:
@@ -72,28 +49,44 @@ jobs:
         with:
           name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
           path: ./wheelhouse/*.whl
-  build_sdist:
-    name: Build source distribution
+  build_python_dists:
+    name: Build native/core/meta sdists and pure wheels
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install dependencies
+      - uses: actions/setup-python@v5
+
+      - name: Install build tooling
         run: |
           python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build native source distribution
+        env:
+          VKDISPATCH_BUILD_TARGET: native
+        run: |
           python fetch_dependencies.py
+          python -m build --sdist --outdir dist
+
+      - name: Build core wheel and source distribution
+        env:
+          VKDISPATCH_BUILD_TARGET: core
+        run: python -m build --wheel --sdist --outdir dist
 
-      - name: Build sdist
-        run: pipx run build --sdist
+      - name: Build meta wheel and source distribution
+        env:
+          VKDISPATCH_BUILD_TARGET: meta
+        run: python -m build --wheel --sdist --outdir dist
 
       - uses: actions/upload-artifact@v4
         with:
-          name: cibw-sdist
-          path: dist/*.tar.gz
+          name: cibw-python-dists
+          path: dist/*
   publish-to-pypi:
     name: Publish Python package to PyPI
     # if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
-    needs: [build_wheels, build_sdist]
+    needs: [build_native_wheels, build_python_dists]
     runs-on: ubuntu-latest
     environment:
       name: pypi

.gitignore

@@ -8,6 +8,11 @@ __pycache__/
 data/
 deps/
 
+codebase.txt
+
+docs/special_pages/libs/vkdispatch
+docs/special_pages/libs/vkdispatch.brython.js
+
 *.png
 *.csv
 *.exec

docs/Makefile

@@ -5,14 +5,39 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
+PYTHON        ?= python
 SOURCEDIR     = .
 BUILDDIR      = _build
 
+# Define destination and filename for the Brython package bundle
+LIB_DEST      = special_pages/libs
+LIB_BUNDLE    = vkdispatch.brython.js
+LIB_STAGE     = $(LIB_DEST)/.vkdispatch_stage
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile bundle_lib
+
+# Target to bundle the library into a single Brython package file
+bundle_lib:
+	@echo "Bundling vkdispatch for Brython..."
+	@$(PYTHON) -c "import brython" > /dev/null
+	@rm -rf "$(LIB_DEST)/vkdispatch"
+	@mkdir -p "$(LIB_DEST)"
+	@rm -f "$(LIB_DEST)/$(LIB_BUNDLE)"
+	@rm -rf "$(LIB_STAGE)"
+	@mkdir -p "$(LIB_STAGE)"
+	@cp -r ../vkdispatch "$(LIB_STAGE)/vkdispatch"
+	@cd "$(LIB_STAGE)" && $(PYTHON) -m brython make_package vkdispatch \
+		--src-dir . \
+		--output-path "$(CURDIR)/$(LIB_DEST)/$(LIB_BUNDLE)"
+	@rm -rf "$(LIB_STAGE)"
+
+# Intercept the "html" target to run bundle_lib first
+html: bundle_lib
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/conf.py

@@ -57,3 +57,4 @@
 
 html_theme = 'alabaster'
 html_static_path = ['_static']
+html_extra_path = ['special_pages']

docs/getting_started.rst

@@ -76,7 +76,8 @@ Next Steps
 
 Now that you've got `vkdispatch` up and running, consider exploring the following:
 
+*   :doc:`Code Structure and Execution Flow<tutorials/code_structure>`: A guided tour of how Python, codegen, and native layers fit together.
 *   :doc:`Tutorials<tutorials/index>`: Our curated guide to the most commonly used classes and functions.
 *   :doc:`Full Python API Reference<python_api>`: A comprehensive list of all Python-facing components.
 
-Happy GPU programming!
+Happy GPU programming!

docs/index.rst

@@ -11,6 +11,7 @@ Welcome to vkdispatch's documentation!
 Welcome to the vkdispatch documentation website!
 
 To learn how to install vkdispatch, go to the :doc:`Getting Started<getting_started>` Section.
+To understand the internals and module layout, start with :doc:`Code Structure and Execution Flow<tutorials/code_structure>`.
 
 Additionally, below are a set of tutorials on vkdispatch usage and a full API reference.
 
@@ -24,6 +25,11 @@ Additionally, below are a set of tutorials on vkdispatch usage and a full API re
 
    Tutorials <tutorials/index>
 
+.. toctree::
+   :maxdepth: 2
+
+   Special <special/index>
+
 .. toctree::
    :maxdepth: 2
 

docs/internal_api.rst

@@ -9,4 +9,4 @@ and the underlying C++/Cython implementation.
    :maxdepth: 2
 
    python_api
-..   cpp_api
+   cpp_api

docs/special/brython_shader_lab.rst

@@ -0,0 +1,16 @@
+Brython Shader Lab
+==================
+
+This page redirects to a standalone HTML app page.
+
+.. raw:: html
+
+   <meta http-equiv="refresh" content="0; url=../brython_shader_lab.html">
+   <script>
+     window.location.replace("../brython_shader_lab.html");
+   </script>
+   <p>
+     Redirecting to the Brython shader lab page.
+     If you are not redirected, open
+     <a href="../brython_shader_lab.html">the standalone HTML page</a>.
+   </p>

docs/special/index.rst

@@ -0,0 +1,9 @@
+Special Pages
+=============
+
+Standalone pages integrated into the docs navigation.
+
+.. toctree::
+   :maxdepth: 1
+
+   brython_shader_lab