[elijahr]

Resolves #77.

Overview

Following investigation of #77 (where autopxd failed inside an Alpine Linux / musllinux cibuildwheel container because neither libclang.so nor the autopxd2[treesitter] extra was available in the isolated build environment), this PR provides clearer guidance, explicit documentation of backend limitations, and a more actionable error message.

Changes

1. CLI Error Message (autopxd/__init__.py):

   • When libclang is requested or resolved but unavailable, the error message now lists package managers for common Linux distributions (including Alpine apk add clang-dev).
   • Clearly points to the tree-sitter alternative (pip install "autopxd2[treesitter]" + autopxd --backend tree-sitter) while explicitly noting that it is more limited (single file only, no #include recursion, no #define macros).
   • Added unit test in test/test_cli.py to verify this guidance.

2. System Package Managers (README.md, docs/getting-started/installation.md):

   • Added Alpine Linux / musl: apk add clang-dev.

3. Headless CI & Build Containers Guide (README.md, docs/getting-started/installation.md):

   • Added a section explaining how to configure container builds (cibuildwheel, Docker, minimal runner images) either by installing libclang (e.g. before-all = "apk add clang-dev") or by declaring autopxd2[treesitter] in build-system.requires.

4. Tree-sitter Limitations & Trade-offs (README.md, docs/user-guide/backends.md):

   • Clarified in detail what tree-sitter does and does not support compared to libclang (no #include expansion, no #define macro extraction, no system include detection, rejects --std/--clang-arg).
   • Outlined guidance on when to choose tree-sitter vs libclang.

5. Changelog (CHANGELOG.md):

   • Documented the changes under [Unreleased].