Modernization phase 1.4 (#1797)

* add feature branch audit file

* Phase 1.4: Migrate build backend from setuptools to hatchling (#1795)

- Replace setuptools with hatchling as build backend
- Add hatch_build.py custom build hook for CFFI NVX extensions
- Remove setup.py and MANIFEST.in (no longer needed with hatchling)
- Add setuptools to build dependencies (required by CFFI on Python 3.12+)
- Update .gitignore to exclude CFFI build artifacts (*.o, _nvx_*.c)
- Hatchling is git-aware: sdist now includes all tracked files by default

Note: This work was completed with AI assistance (Claude Code).

* fix(ci): build NVX CFFI modules for editable installs

Add `build-nvx` recipe that compiles the NVX CFFI modules (UTF-8
validator and XOR masker) for development/editable installs.

The hatchling custom build hook only compiles CFFI modules during
wheel builds. For editable installs in CI or local development,
we need to compile them manually. The `.so` files are placed in
`src/` (not `src/autobahn/nvx/`) because CFFI names the modules
as top-level modules that Python looks for in sys.path roots.

Changes:
- Add `build-nvx` recipe to justfile
- Update `install-tools` to call `build-nvx` after editable install
- Change VENV_DIR to absolute path (PROJECT_DIR / '.venvs') to avoid
  path issues when cd'ing in subshells

This fixes CI failures when running tests with AUTOBAHN_USE_NVX=1.

Note: This work was completed with AI assistance (Claude Code).

* fix(ci): place NVX .so at wheel root and fix PyPy ARM64 build

Two fixes for CI failures:

1. hatch_build.py: Place NVX .so files at WHEEL ROOT (not autobahn/nvx/)
   - CFFI creates top-level modules (e.g., "_nvx_utf8validator")
   - Python imports them as `import _nvx_utf8validator` (top-level)
   - When installed from wheel, the .so must be in site-packages root
   - This fixes: "RuntimeError: NVX native acceleration explicitly
     requested via AUTOBAHN_USE_NVX=1, but NVX modules are not available"

2. build-arm64-wheel.sh: Disable py-ubjson C extension for PyPy on ARM64
   - The C extension segfaults (exit -11) under QEMU ARM64 emulation
   - py-ubjson works fine as pure Python under PyPy's JIT
   - Sets PYUBJSON_NO_EXTENSION=1 when building for PyPy

Note: This work was completed with AI assistance (Claude Code).

* Update txaio dependency to >=25.12.2

Align with the latest txaio release which uses hatchling build backend.

Note: This work was completed with AI assistance (Claude Code).

* Add Autobahn logo to documentation with scour optimization

- Add autobahn_logo_blue.svg to docs/_graphics/ (source)
- Add _build-images just recipe to optimize SVGs using scour
- Update docs recipe to call _build-images before sphinx-build
- Add html_logo to conf.py pointing to optimized logo
- Add scour>=0.38 to dev dependencies
- Add docs/_static/img/ to .gitignore (generated files)

Note: This work was completed with AI assistance (Claude Code).

* Add install-dev-latest and install-dev-local recipes

- Add dev-latest optional dependency for GitHub master branches
- Add [tool.hatch.metadata] allow-direct-references = true
- Add install-dev-latest just recipe for GitHub dependencies
- Add install-dev-local just recipe for local sibling repos

This enables development when upstream WAMP packages (txaio) have
unreleased versions not yet on PyPI.

Note: This work was completed with AI assistance (Claude Code).

* docs: standardize Sphinx configuration across WAMP projects

- Modernize conf.py with Furo theme and Noto fonts from Google Fonts
- Standardize extensions, project metadata, and spelling configuration
- Add docs-spelling just recipe for spell checking

Note: This work was completed with AI assistance (Claude Code).

* docs: add install-docs just recipe

Add missing install-docs recipe required by docs-spelling and
_build-images recipes.

Note: This work was completed with AI assistance (Claude Code).

* build: add docs optional dependency for Sphinx documentation

Add [docs] optional dependency group to pyproject.toml with all
required Sphinx extensions and tools for documentation building.

Note: This work was completed with AI assistance (Claude Code).

* docs: add ai/index.rst and refactor AI Policy section

- Create docs/ai/index.rst to collect AI-related documentation
- Update docs/index.rst to link to ai/index instead of listing files directly

Note: This work was completed with AI assistance (Claude Code).

* Update .ai submodule with OVERVIEW.md

- Update .ai submodule to include OVERVIEW.md with wamp-xbr section
- OVERVIEW.md symlink already exists (via just setup-repo)
- docs/OVERVIEW.md already in toctree

OVERVIEW.md provides context about the WAMP project ecosystem.

Note: This work was completed with AI assistance (Claude Code).

* Modernize Sphinx docs: Furo theme, branding, favicon

- Add optimize-images recipe with SVG optimization and favicon generation
- Update conf.py with Autobahn Medium Blue (#027eae) brand colors
- Add html_favicon setting for browser tab icon
- Add pygments_dark_style for dark mode code highlighting
- Update docs recipe to depend on optimize-images

Part of docs consistency effort across WAMP Python projects.

Note: This work was completed with AI assistance (Claude Code).

* add after sync-images

* Standardize docs: .gitignore and AutoAPI configuration

- Add .build/ to .gitignore
- Standardize AutoAPI config to match txaio pattern:
  - autoapi_add_toctree_entry = True
  - autoapi_keep_files = False
  - autoapi_generate_api_docs = True
  - autoapi_member_order = "alphabetical"
  - Consistent autoapi_options and autoapi_ignore patterns

Note: This work was completed with AI assistance (Claude Code).

* Standardize docs: autoapi options, standalone index.rst

- Add private-members and special-members to autoapi_options
- Remove README.md symlink, create standalone index.rst
- Update page title to "WebSocket & WAMP for Python on Twisted and asyncio"

Note: This work was completed with AI assistance (Claude Code).

* Add AI_ACKNOWLEDGEMENT.md symlink to docs/ai

- Create symlink to .ai/AI_ACKNOWLEDGEMENT.md
- Reference in docs/ai/index.rst toctree

Note: This work was completed with AI assistance (Claude Code).

* Standardize docs ToC structure per STD-TOC.md

Add standard documentation sections:
- overview.rst
- getting-started.rst
- contributing.rst
- programming-guide/ folder with index and subsections

Update index.rst with standardized ToC order:
Overview, Installation, Getting Started, Programming Guide,
Releases, Changelog, Contributing, WAMP Projects, AI Policy

Note: This work was completed with AI assistance (Claude Code).

* Standardize LICENSE with SPDX header and add docs copyright footer

- Add YAML-formatted SPDX license metadata header to LICENSE
- Add copyright/trademark footer to docs/index.rst
- MIT license year based on first git commit (2011)

Note: This work was completed with AI assistance (Claude Code).

* Consolidate docs: CONTRIBUTING.md, RTD config, remove stale files

- Update CONTRIBUTING.md with modern contribution guidelines
- Add .readthedocs.yaml for consistent RTD builds with docs dependency
- Update docs/contributing.rst to include CONTRIBUTING.md via MyST parser
- Remove outdated ephemeral dev notes (ENUMERATION_AUDIT*.md, etc.)

Note: This work was completed with AI assistance (Claude Code).

* docs: Rename Overview to Introduction

Standardize documentation page titles across the WAMP project group:
- Rename 'Overview' page to 'Introduction'

Note: This work was completed with AI assistance (Claude Code).

* docs: Add sphinx_auto_section_anchors + release workflow recipes

- Update .cicd submodule to include sphinx_auto_section_anchors extension
- Add extension to docs/conf.py with path to .cicd/scripts
- Add Release Artifacts links (GitHub/PyPI/RTD) to each version in release-notes.rst
- Add Release Workflow documentation section for maintainers
- Add prepare-changelog, draft-release, prepare-release justfile recipes

Note: This work was completed with AI assistance (Claude Code).

* docs: Enable auto_section_anchor_force for stable HTML anchors

This ensures the sphinx_auto_section_anchors extension overwrites
auto-generated ids (id1, id2, etc.) with slug-based anchors like
#25-12-1 instead of #id3.

Note: This work was completed with AI assistance (Claude Code).

* docs: Add git hooks steps to release workflow

- Add Step 4: Disable Git Hooks (if needed)
- Add Step 6: Enable Git Hooks (if previously disabled)
- Renumber remaining steps accordingly

Note: This work was completed with AI assistance (Claude Code).

* Standardize project badges

- Add 6 core badges: PyPI, Python, CI, Docs (RTD), License, Downloads
- Add 4 additional CI/CD badges: wstest, wheels, wheels-arm64, wheels-docker
- Apply consistent badge format to both README.md and docs/index.rst
- Use RTD native badge for documentation status

Note: This work was completed with AI assistance (Claude Code).

* Update .cicd submodule: fix linting error

Pull in wamp-cicd commit 08c9305 which removes unused variable
in sphinx_auto_section_anchors.py (F841 linting error).

Note: This work was completed with AI assistance (Claude Code).

* Fix RST badge rendering: disable override_image_directive

Set override_image_directive=False in sphinxcontrib-images config
to preserve standard RST image directive :target: option support.

This fixes badge substitutions in docs/index.rst that require the
:target: option for clickable badge links.

Note: This work was completed with AI assistance (Claude Code).

* Add conf.py comment and require Sphinx>=8.2.3

- Add explanatory comment for override_image_directive=False setting
  explaining it's required for RST badge :target: option support
- Update sphinx>=8.2.3 in docs optional dependency (highest version
  compatible with furo's sphinx<9.0 constraint)

Note: This work was completed with AI assistance (Claude Code).

* Add submodules config to .readthedocs.yaml for RTD builds

Required for .cicd submodule containing sphinx_auto_section_anchors.py
extension used in docs/conf.py.

Note: This work was completed with AI assistance (Claude Code).

* Fix RTD submodules configuration (remove invalid depth key)

Use explicit submodule list instead of 'include: all':
- .ai for AI/audit docs
- .cicd for sphinx_auto_section_anchors extension

Note: This work was completed with AI assistance (Claude Code).

Author: oberstet

.ai

@@ -0,0 +1,8 @@
+- [ ] I did **not** use any AI-assistance tools to help create this pull request.
+- [x] I **did** use AI-assistance tools to *help* create this pull request.
+- [x] I have read, understood and followed the project's AI_POLICY.md when creating code, documentation etc. for this pull request.
+
+Submitted by: @oberstet
+Date: 2025-12-05
+Related issue(s): #1795
+Branch: oberstet:modernization-phase-1.4

.audit/oberstet_modernization-phase-14.md

@@ -50,6 +50,14 @@ echo "auditwheel: $(auditwheel --version || echo 'not available')"
 # nh3 is a Rust package (indirect dep of twine) that segfaults under QEMU
 export AUTOBAHN_USE_NVX=1
 
+# Disable py-ubjson C extension for PyPy on ARM64
+# The C extension build segfaults under QEMU ARM64 emulation (exit code -11)
+# py-ubjson works fine as pure Python under PyPy's JIT
+if python3 -c "import platform; exit(0 if 'pypy' in platform.python_implementation().lower() else 1)" 2>/dev/null; then
+  echo "==> PyPy detected: disabling py-ubjson C extension (QEMU ARM64 incompatible)"
+  export PYUBJSON_NO_EXTENSION=1
+fi
+
 # Build only specified Python versions (or all if not specified)
 if [ -n "$PYTHON_VERSIONS" ]; then
   echo "==> Building wheels for specific Python versions: $PYTHON_VERSIONS"

.cicd

@@ -39,9 +39,15 @@ node.key
 *.swo
 *.swn
 *.so
+*.o
+
+# CFFI-generated intermediate C files (NVX extension modules)
+src/autobahn/nvx/_nvx_*.c
+
 .wheels
 get-pip.py
 docs/autoapi/
+.build/
 key.pub
 key.priv
 node_modules/
@@ -53,6 +59,7 @@ wheelhouse/
 .wstest/
 docs/_static/websocket/conformance/
 docs/_static/flatbuffers/
+docs/_static/img/
 .coverage.*
 examples/benchmarks/serialization/build/
 

.github/scripts/build-arm64-wheel.sh

@@ -0,0 +1,34 @@
+# .readthedocs.yaml
+# Read the Docs configuration file for autobahn
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+# Include .ai submodule for AI/audit related docs to be included in built docs (via symlinks)
+# Include .cicd submodule for shared Sphinx extensions (sphinx_auto_section_anchors)
+submodules:
+  include:
+    - .ai
+    - .cicd
+  recursive: false
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+  # Install system packages for spell checking
+  apt_packages:
+    - libenchant-2-2
+
+sphinx:
+  configuration: docs/conf.py
+  builder: html
+  fail_on_warning: false
+
+python:
+  install:
+    # Install the package with docs dependencies
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs