sharhar · sharhar · Sep 9, 2025 · Sep 9, 2025 · Sep 9, 2025 · Sep 9, 2025
diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml
@@ -0,0 +1,73 @@
+name: Deploy Sphinx docs to GitHub Pages
+
+on:
+  push:
+    branches: [ docs ]
+    paths:
+      - 'docs/**'
+      - '**.py'
+      - 'pyproject.toml'
+      - 'setup.py'
+      - 'README*'
+  workflow_dispatch: {}   # Manual “Run workflow” button
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+          cache: 'pip'
+          cache-dependency-path: 'docs/requirements.txt'
+
+      - name: Install build dependencies
+        run: |
+          sudo apt-get update
+          # Install system packages required for exhale/breathe
+          sudo apt-get install -y doxygen graphviz
+
+          python -m pip install --upgrade pip
+          # Always install sphinx and required extensions
+          python -m pip install \
+            "sphinx>=7,<9" \
+            sphinx-rtd-theme
+
+          # If your docs import your package (autodoc), also install it:
+          # python -m pip install -e .
+
+      - name: Build Sphinx HTML
+        working-directory: docs
+        run: |
+          make clean html
+
+      - name: Add .nojekyll (avoid Jekyll processing on GitHub Pages)
+        run: |
+          touch docs/_build/html/.nojekyll
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
@@ -1,24 +1,65 @@
-# vkdispatch
-A Python module for orchestrating and dispatching large computations across multi-GPU systems using Vulkan.
+# Getting Started / Installation
 
+Welcome to **vkdispatch**! This guide will help you install the library and run your first GPU-accelerated code.
 
-## Instillation
+> **Note:** vkdispatch requires a Vulkan-compatible GPU and drivers installed on your system. Please ensure your system meets these requirements before proceeding.
 
-The vkdispatch package can be installed via Pypi using
+## PyPI
 
-```
+The default installation method for `vkdispatch` is through PyPI (pip):
+
+```bash
+# Install the package
 pip install vkdispatch
 ```
 
-### Local instillation
+On mainstream platforms — Windows (x86_64), macOS (x86_64 and Apple Silicon/arm64), and Linux (x86_64) — pip will download a **prebuilt wheel** (built with `cibuildwheel` on GitHub Actions and tagged as *manylinux* where applicable), so no compiler is needed.
+
+On less common platforms (e.g., non-Apple ARM or other niche architectures), pip may fall back to a **source build**, which takes a few minutes. See **[Building From Source](https://sharhar.github.io/vkdispatch/tutorials/building_from_source.html)** for toolchain requirements and developer-oriented instructions.
+
+> **Tip:** If you see output like `Building wheel for vkdispatch (pyproject.toml)`, you’re compiling from source.
 
-If you want a local install of vkdispatch (e.g. for development purposes), then use the following steps to build from source.
-Note that its recommended to use a Python environment manager for development
+## Verifying Your Installation
 
+To ensure `vkdispatch` is installed correctly and can detect your GPU, run:
+
+```bash
+# Quick device listing
+vdlist
+
+# If the above command is unavailable, try:
+python3 -m vkdispatch
 ```
-git clone https://github.com/sharhar/vkdispatch.git
-cd vkdispatch
-python fetch_dependencies.py
-pip install -r requirements.txt
-pip install -e .
+
+If the installation was successful, you should see output listing your GPU(s), for example:
+
+```text
+Device 0: Apple M2 Pro
+    Vulkan Version: 1.2.283
+    Device Type: Integrated GPU
+
+    Features:
+        Float32 Atomic Add: True
+
+    Properties:
+        64-bit Float Support: False
+        16-bit Float Support: True
+        64-bit Int Support: True
+        16-bit Int Support: True
+        Max Push Constant Size: 4096 bytes
+        Subgroup Size: 32
+        Max Compute Shared Memory Size: 32768
+
+    Queues:
+        0 (count=1, flags=0x7): Graphics | Compute
+        1 (count=1, flags=0x7): Graphics | Compute
+        2 (count=1, flags=0x7): Graphics | Compute
+        3 (count=1, flags=0x7): Graphics | Compute
 ```
+
+## Next Steps
+
+- **[Tutorials](https://sharhar.github.io/vkdispatch/tutorials/index.html)** — our curated guide to common workflows and examples
+- **[Full Python API Reference](https://sharhar.github.io/vkdispatch/python_api.html)** — comprehensive reference for Python-facing components
+
+Happy GPU programming!
diff --git a/TODOs.txt b/TODOs.txt
diff --git a/docs/conf.py b/docs/conf.py
@@ -21,31 +21,31 @@
 extensions = [
     'sphinx.ext.autodoc',  # For Python docstrings
     'sphinx.ext.napoleon', # To support Google/Numpy style docstrings
-    'breathe',             # The Doxygen-Sphinx bridge
-    'exhale',              # The automation layer for Breathe
-    'myst_parser',         # For Markdown support
+#    'breathe',             # The Doxygen-Sphinx bridge
+#    'exhale',              # The automation layer for Breathe
+#    'myst_parser',         # For Markdown support
 ]
-breathe_projects = {
-    "vkdispatch": "../build/doxyoutput/xml" # Path to Doxygen's XML output
-}
-breathe_default_project = "vkdispatch"
-
-exhale_args = {
-    # These arguments are required
-    "containmentFolder":     "./api",
-    "rootFileName":          "library_root.rst",
-    "doxygenStripFromPath":  "..",
-    # Suggested optional arguments
-    "createTreeView":        True,
-    "exhaleExecutesDoxygen": True,
-    "exhaleDoxygenStdin":    "INPUT = ../vkdispatch_native2", # Path to your C++ source
-}
+# breathe_projects = {
+#     "vkdispatch": "../build/doxyoutput/xml" # Path to Doxygen's XML output
+# }
+#breathe_default_project = "vkdispatch"
+
+# exhale_args = {
+#     # These arguments are required
+#     "containmentFolder":     "./api",
+#     "rootFileName":          "library_root.rst",
+#     "doxygenStripFromPath":  "..",
+#     # Suggested optional arguments
+#     "createTreeView":        True,
+#     "exhaleExecutesDoxygen": True,
+#     "exhaleDoxygenStdin":    "INPUT = ../vkdispatch_native2", # Path to your C++ source
+# }
 
 # Tell sphinx what the primary language being documented is.
-primary_domain = 'cpp'
+# primary_domain = 'cpp'
 
 # Tell sphinx what the pygments highlight language should be.
-highlight_language = 'cpp'
+# highlight_language = 'cpp'
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

diff --git a/docs/cpp_api.rst b/docs/cpp_api.rst
@@ -1,7 +1,7 @@
 C++/Cython API Reference
 ========================
 
-.. toctree::
-   :maxdepth: 3
+.. .. toctree
+..    :maxdepth: 3
 
-   api/library_root
+..    api/library_root
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -1,4 +1,4 @@
-Getting Started with vkdispatch
+Getting Started/Installation
 ===============================
 
 Welcome to vkdispatch! This guide will help you install the library and run your first GPU-accelerated code.
@@ -7,22 +7,27 @@ Welcome to vkdispatch! This guide will help you install the library and run your
    vkdispatch requires a Vulkan-compatible GPU and drivers installed on your system.
    Please ensure your system meets these requirements before proceeding.
 
-Installation
-------------
+PyPI
+----
 
-You can install `vkdispatch` directly from PyPI using `pip`. We recommend
-using a `virtual environment`_ for your projects.
+The default installation method for `vkdispatch` is through PyPI (pip):
 
 .. code-block:: bash
 
-   # Create a virtual environment (optional, but recommended)
-   python -m venv venv
-   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
-
-   # Install vkdispatch
+   # Install the package
    pip install vkdispatch
 
-.. _virtual environment: https://docs.python.org/3/library/venv.html
+On mainstream platforms — Windows (x86_64), macOS (x86_64 and Apple Silicon/arm64),
+and Linux (x86_64) — pip will download a **prebuilt wheel** (built with `cibuildwheel`
+on GitHub Actions and tagged as *manylinux* where applicable), so no compiler is needed.
+
+On less common platforms (e.g., non-Apple ARM or other niche architectures), pip may
+fall back to a **source build**, which takes a few minutes. See :doc:`Building From Source<tutorials/building_from_source>`
+for toolchain requirements and developer-oriented instructions.
+
+.. note::
+   If you see output like ``Building wheel for vkdispatch (pyproject.toml)``,
+   you’re compiling from source.
 
 Verifying Your Installation
 ---------------------------
@@ -31,56 +36,47 @@ To ensure `vkdispatch` is installed correctly and can detect your GPU,
 run this simple Python script:
 
 .. code-block:: bash
+
    # Run the example script to verify installation
    vdlist
 
    # If the above command fails, you can try this alternative
    python3 -m vkdispatch
 
-If the installation was successful, you should see output listing your GPU(s).
-
-Your First GPU Buffer
----------------------
+If the installation was successful, you should see output listing your GPU(s) which may look something like this:
 
-Let's create a simple GPU buffer and fill it with data.
+.. code-block:: text
 
-.. literalinclude:: ../examples/first_buffer.py
-   :language: python
-   :linenos:
-   :caption: examples/first_buffer.py
+   Device 0: Apple M2 Pro
+        Vulkan Version: 1.2.283
+        Device Type: Integrated GPU
 
-.. raw:: html
+        Features:
+                Float32 Atomic Add: True
 
-.. code-block:: text
+        Properties:
+                64-bit Float Support: False
+                16-bit Float Support: True
+                64-bit Int Support: True
+                16-bit Int Support: True
+                Max Push Constant Size: 4096 bytes
+                Subgroup Size: 32
+                Max Compute Shared Memory Size: 32768
 
-      # Expected Output:
-      # Original CPU data: [ 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15]
-      # Data downloaded from GPU: [ 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15]
-
+        Queues:
+                0 (count=1, flags=0x7): Graphics | Compute
+                1 (count=1, flags=0x7): Graphics | Compute
+                2 (count=1, flags=0x7): Graphics | Compute
+                3 (count=1, flags=0x7): Graphics | Compute
 
-.. admonition:: What's happening here?
-   :class: tip
 
-   1.  We import `vkdispatch` and `numpy` (a common dependency for numerical data).
-   2.  A `BufferBuilder` is used to define the characteristics of our GPU buffer (size, usage).
-   3.  `buffer.upload()` transfers data from your CPU's memory to the GPU.
-   4.  `buffer.download()` retrieves data back from the GPU to the CPU.
-   5.  Error checking is crucial in GPU programming, so `check_for_errors()` ensures operations completed successfully.
 
 Next Steps
 ----------
 
-Now that you've got `vkdispatch` up and running, consider exploring:
-
-*   **Public API Reference:** Our curated guide to the most commonly used classes and functions.
-*   **Full Python API Reference:** A comprehensive list of all Python-facing components.
-*   **C++/Cython API Reference:** Dive deep into the backend details.
-
-Happy GPU programming!
+Now that you've got `vkdispatch` up and running, consider exploring the following:
 
-.. seealso::
+*   :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.
 
-   :doc:`public_api/index`
-      Start here for a guided tour of core features.
-   :doc:`buffer_management`
-      Detailed information on working with GPU buffers.
+Happy GPU programming!
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,20 +6,29 @@
 Welcome to vkdispatch's documentation!
 ======================================
 
+**[WARNING: This site is still under heavy development, and has many missing sections]**
+
+Welcome to the vkdispatch documentation website!
+
+To learn how to install vkdispatch, go to the :doc:`Getting Started<getting_started>` Section.
+
+Additionally, below are a set of tutorials on vkdispatch usage and a full API reference.
+
 .. toctree::
-   :maxdepth: 2
-   :caption: User Guide:
+   :hidden:
 
    getting_started
-   public_api/index
 
 .. toctree::
    :maxdepth: 2
-   :caption: Full Internal Documentation:
 
-   internal_api
+   Tutorials <tutorials/index>
+
+.. toctree::
+   :maxdepth: 2
+
+   Full Internal Documentation <internal_api>
 
-.. include:: ../README.md
 
 
 Indices and tables