docs update

Author: electronstudio

AGENTS.md

@@ -4,37 +4,55 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is raylib-python-cffi8, Python CFFI bindings for Raylib 5.5 game development library. It provides two main Python modules:
-- `raylib`: Direct C API bindings (exact copy of C functions)  
+This is **raylib-python-cffi** (version 6.0.1.0), Python CFFI bindings for Raylib 6.0 game development library. It provides two main Python modules:
+- `raylib`: Direct C API bindings (exact copy of C functions)
 - `pyray`: More Pythonic API wrapper
 
+Also includes bindings for raymath, raygui, rlgl, physac, and GLFW.
+
 ## Key Architecture
 
 - `/raylib/`: Core static CFFI bindings module with build system
-- `/pyray/`: Pythonic wrapper API module
-- `/dynamic/`: Dynamic binding version (separate package)
-- `/examples/`: Python example code organized by category (core, audio, textures, etc.)
+  - `build.py` — Main CFFI build entry point; parses C headers and generates bindings
+  - `__init__.py` — Module init, loads compiled CFFI extension
+  - `colors.py`, `enums.py`, `defines.py` — Generated Python constants
+- `/pyray/`: Pythonic wrapper API module around `raylib`
+- `/dynamic/`: Dynamic binding version (separate `raylib_dynamic` package)
+  - `setup.py` — Separate setuptools config for dynamic build
+  - `raylib/__init__.py` — Runtime-loaded dynamic bindings
+- `/examples/`: Python example code organized by category (core, textures, shapes, models, shaders, physics, audio, raygui, extra)
+- `/tests/`: Test scripts for both static and dynamic versions
 - `/raylib-c/`: Embedded Raylib C library source (git submodule)
-- `/raygui/`: Embedded raygui C library source (git submodule)  
+- `/raygui/`: Embedded raygui C library source (git submodule)
 - `/physac/`: Embedded physac physics library source
-- `/tests/`: Test scripts for both static and dynamic versions
+- `/docs-src/`: Sphinx documentation source
+- `/docs/`: Pre-built HTML documentation (hosted on GitHub Pages)
+- `setup.py` — Main setuptools entry point for static builds
+- `version.py` — Single source of truth for package version
 
 ## Build System
 
 The project uses CFFI with setuptools. Main build entry point is `raylib/build.py` which:
-- Parses C headers from embedded libraries
-- Generates CFFI bindings
+- Parses C headers from embedded libraries (`raylib-c/src/raylib.h`, etc.)
+- Generates CFFI bindings (`_raylib_cffi.c`)
+- Compiles platform-specific extension modules
 - Handles platform-specific linking (Desktop/SDL/DRM backends)
 - Supports environment variable customization for build paths
 
+### Package names by platform
+- Default: `raylib`
+- SDL backend: `raylib_sdl`
+- DRM backend: `raylib_drm`
+- Software rendering (SDL): `_software` (name suffix)
+
 ## Development Commands
 
 ### Building from source
 ```bash
-# Build Python library manually
+# Build Python library manually (generates CFFI bindings + compiles)
 python3 raylib/build.py
 
-# Build wheel distribution  
+# Build wheel distribution
 pip3 install wheel
 python3 setup.py bdist_wheel
 
@@ -44,13 +62,13 @@ pip3 install dist/raylib*.whl
 
 ### Testing
 ```bash
-# Run main test suite
+# Run main static test suite
 cd tests && ./run_tests.sh
 
-# Run dynamic version tests  
+# Run dynamic version tests
 cd tests && ./run_tests_dynamic.sh
 
-# Individual test files can be run with python3
+# Individual test files
 python3 tests/test_hello_world.py
 ```
 
@@ -71,19 +89,85 @@ python3 tests/test_hello_world.py
 
 ## Environment Variables for Build Customization
 
-- `RAYLIB_PLATFORM`: Desktop (default), SDL, DRM, PLATFORM_COMMA
+- `RAYLIB_PLATFORM`: Desktop (default), SDL, DRM, PLATFORM_COMMA, SDL_SOFT
 - `RAYLIB_LINK_ARGS`: Manual linker arguments instead of pkg-config
-- `RAYLIB_INCLUDE_PATH`: Custom path to raylib.h
-- `RAYGUI_INCLUDE_PATH`: Custom path to raygui.h  
-- `GLFW_INCLUDE_PATH`: Custom path to glfw3.h
-- `PHYSAC_INCLUDE_PATH`: Custom path to physac.h
+- `RAYLIB_INCLUDE_PATH`: Custom path to `raylib.h`
+- `RAYGUI_INCLUDE_PATH`: Custom path to `raygui.h`
+- `GLFW_INCLUDE_PATH`: Custom path to `glfw3.h`
+- `PHYSAC_INCLUDE_PATH`: Custom path to `physac.h`
+- `PKG_CONFIG_LIB_raylib`: pkg-config package name for raylib (default `raylib`)
+- `PKG_CONFIG_LIB_raygui`: pkg-config package name for raygui (default `raygui`)
 
 ## Package Variants
 
-The project can be built as different packages:
+The project publishes multiple mutually exclusive PyPI packages:
 - `raylib`: Standard desktop version
-- `raylib_sdl`: SDL backend version  
+- `raylib_sdl`: SDL backend version
 - `raylib_drm`: DRM framebuffer version
-- `raylib_dynamic`: Dynamic linking version (separate dynamic/ directory)
+- `raylib_dynamic`: Dynamic linking version (separate `dynamic/` directory)
+
+Only one can be installed at a time.
+
+## GitHub Actions Workflows
+
+### `.github/workflows/build.yml`
+
+The main CI/CD workflow. Triggered on push, pull request, and manual dispatch.
+
+**Jobs:**
+- `build-mac-intel` — macOS Intel runners (`macos-15-intel`), Python 3.7–3.14 + PyPy 3.11, Desktop/SDL platforms
+- `build-mac-arm64` — macOS ARM64 (`macos-14`), Python 3.10–3.14, Desktop/SDL platforms
+- `build-linux` — Ubuntu 16 container (`electronstudio/ubuntu16-modern`), Python 3.7–3.14 + PyPy 3.11, Desktop/SDL/DRM/SDL_SOFT platforms
+- `build-linux32` — 32-bit Ubuntu 16 container, same Python versions and platforms
+- `build-linux-arm64` — Ubuntu ARM64 (`ubuntu-22.04-arm`), Python 3.10–3.14, Desktop/SDL/SDL_SOFT
+- `build-linux-arm64-drm` — Raspberry Pi OS containers (Bullseye/Bookworm), Python 3.10–3.14, DRM only
+- `build-windows` — Windows Server 2022, Python 3.7–3.14 + PyPy 3.11, Desktop/SDL/SDL_SOFT, x64
+- `build-windows32` — Windows Server 2022, same Python versions, x86
+- `source-distro` — Builds and publishes sdist
+- `dynamic-distro` — Builds and publishes `raylib_dynamic` sdist
+- `merge` — Merges all artifact uploads
+
+**Manual dispatch inputs:**
+- `publish_to_pypi` (boolean): Publish wheels to PyPI after build. Requires `PYPI_KEY` secret.
+
+All build jobs perform a smoke test after building: `import pyray; pyray.init_window(100,100,"test")`, checking output for `"INFO: Initializing raylib"`.
+
+### `.github/workflows/test_pypi.yml`
+
+On-demand workflow to verify packages work when installed directly from PyPI. Triggered manually via `workflow_dispatch`.
+
+**Inputs:**
+- `package_name` (string): Which package to test (`raylib`, `raylib_sdl`, `raylib_drm`, `raylib_dynamic`) — default `raylib`
+- `version` (string): Specific version to install (e.g., `5.5.0.2`) — leave empty for latest
+- `pre_release` (boolean): Whether to pass `--pre` to pip to allow pre-release versions
+
+**Matrix:**
+- OS: macOS Intel (`macos-15-intel`) and macOS ARM64 (`macos-14`)
+- Python versions: 3.10, 3.11, 3.12, 3.13, 3.14
+- Python source: Homebrew (`brew install python@X.Y`) and python.org (`actions/setup-python`)
+
+The workflow installs the selected package from PyPI and runs the same smoke test (`import pyray; pyray.init_window(...)`) to verify the installed wheel works correctly.
+
+## Testing Structure
+
+- `test_*.py` — Standard tests (run by `run_tests.sh`)
+- `xtest_*.py` — Extra/manual tests (not run by default scripts)
+- `test_hello_world.py` — Minimal smoke test for basic import and window init
+- `test_pyray.py` — Tests the `pyray` wrapper API
+- `test_static_with_only_api_from_dynamic.py` — Ensures static API matches dynamic
+- `test_color.py`, `test_float_pointers.py` — Type/struct sanity checks
+- `test_gamepad.py`, `test_raygui_style.py` — Feature-specific tests
+
+## Documentation
+
+- Source: `/docs-src/` (Sphinx reStructuredText)
+- Built output: `/docs/` (HTML, committed for GitHub Pages)
+- Hosted at: https://electronstudio.github.io/raylib-python-cffi
+- `make_docs.sh` regenerates `/docs/` from `/docs-src/`
+
+## Notes for Contributors
 
-These are mutually exclusive - only one can be installed at a time.
+- The `version.py` file is the single source of truth for the package version.
+- CFFI bindings are generated at build time from headers in `raylib-c/src/`, `raygui/src/`, `physac/src/`.
+- Submodules must be initialized (`git submodule update --init --recursive`) before building.
+- The `raygui.h.diff` patch is applied in CI to fix a raygui bug before compilation.

AI_POLICY.md

@@ -1,3 +1,5 @@
+# AI Policy
+
 AI will be used in this project only when it is impossible to tell that it has been used.
 
 Given the current state of AI in 2026, this in practise means:

README.md

@@ -33,8 +33,6 @@ while not window_should_close():
 close_window()
 ```
 
-
-
 Use the [project generator](https://github.com/electronstudio/python-raylib-template) to generate a complete project.  [Example of project](https://github.com/electronstudio/raylib-example-game)
 
 # Videos
@@ -59,6 +57,7 @@ Use the [project generator](https://github.com/electronstudio/python-raylib-temp
 * [Python video player](https://github.com/anrayliu/pyvidplayer2)
 * [A Vector2 class](https://github.com/electronstudio/raylib-python-cffi/blob/master/examples/extra/vector2_extended.py)
 * [Raylib C FAQ](https://github.com/raysan5/raylib/wiki/Frequently-Asked-Questions/)
+* [Project generator](https://github.com/electronstudio/python-raylib-template)
 
 # Installation
 
@@ -216,6 +215,16 @@ Carefully read all their [documentation](https://pygame-web.github.io/).
 
 It does work for most of [these examples](https://electronstudio.github.io/raylib-python-cffi-pygbag-examples/)
 
+# Startup without printing anything
+
+```python
+import logging
+logging.basicConfig(level=logging.ERROR)
+import pyray
+pyray.set_trace_log_level(pyray.LOG_ERROR)
+pyray.init_window(100,100,"test")
+```
+
 # App showcase
 
 [Tempest-raylib](https://github.com/Emtyloc/tempest-raylib)
@@ -230,8 +239,6 @@ It does work for most of [these examples](https://electronstudio.github.io/rayli
 
 [Alloy Bloxel Editor](https://pebaz.itch.io/alloy-bloxel-editor)
 
-[Eidolon](https://github.com/Miou-zora/Eidolon)
-
 Add your app here!
 
 # RLZero
@@ -297,3 +304,7 @@ You can create a standalone binary using the Nuitka compiler.  For example, here
 
 [Coding Games With Pygame Zero & Python](https://github.com/electronstudio/pygame-zero-book) is 
 a book for Python beginners.
+
+# Hall of shame!
+
+Apparently [comma.ai](https://comma.ai/) are now using raylib-python-cffi commercially and so have begun donating money to raylib but have chosen _not_ to give anything to raylib-python-cffi.  Yes it's perfectly legal usage, but it's not very nice behaviour.  😔

RPI.rst

@@ -6,13 +6,13 @@ Please use Raspberry Pi OS 13 Trixie 64 bit.  Bookworm should also work.  Older
 Option 1: Binary wheel
 ----------------------
 
-We have published binary wheels compiled for 64-bit Raspberry OS 12 Bookworm in X11 mode.
+We have published binary wheels compiled for 64-bit Raspberry OS 12 Bookworm in Wayland/X11 mode.
 
 ::
 
     python -m pip install --break-system-packages raylib
 
-Alternatively there is a DRM wheel called ``raylib_drm`` to use the framebuffer without X11.  You can't have both wheels
+Alternatively there is a DRM wheel called ``raylib_drm`` to use the framebuffer mode.  You can't have both wheels
 installed at once.
 
 If it doesn't work, or you're not on Bookworm/Trixie, or you're 32 bit, you will need to compile your own raylib.  See below.
@@ -79,7 +79,7 @@ Build a shared lib version of Raylib in DRM mode and install to /usr:
     make
     sudo make install
 
-    
+
 Then have pip compile and install the wheel:
 
 ::

docs-src/AI_POLICY.md

@@ -0,0 +1 @@
+../AI_POLICY.md

docs-src/index.rst

@@ -16,10 +16,7 @@ Raylib Python
    dynamic
    BUILDING
    RPI
+   AI_POLICY
 
 
 * :ref:`search`
-
-
-
-