Contributing¶
Contributions are welcome: bug reports, file-compatibility reports ("software X writes Y"), anonymised or synthetic samples, documentation and code.
| Document | Purpose |
|---|---|
| CONTRIBUTING.md | development setup, tests, adding finding codes, contributing anonymised samples, pull-request checklist |
| ARCHITECTURE.md | a map of the code and the rules every change must keep |
| SUPPORT.md | where to ask for help |
| CODE_OF_CONDUCT.md | Contributor Covenant 3.0 |
| SECURITY.md | supported versions and how to report a vulnerability privately |
| CITATION.cff | how to cite pyxaf (GitHub's "Cite this repository" button reads it) |
| CHANGELOG.md | release notes |
Never share real auditfiles
Never attach, upload, paste or commit a real auditfile from a client or company: not in issues, pull requests, discussions or test fixtures. Share the versions, the exporting software, the finding codes and a minimal hand-made snippet instead. See Privacy.
Working on the documentation¶
The site is built with Zensical from the Markdown files in docs/, with
the API reference generated by mkdocstrings. Configuration lives in zensical.toml.
uvx nox -s docs -- serve # live preview on http://localhost:8000
uvx nox -s docs # check generated pages, build into site/
Two pages are generated from the code and must not be edited by hand:
Finding codes (from pyxaf.findings.CODES) and
Table schemas (from pyxaf.tables.TABLES). After changing codes or
schemas, regenerate them:
uvx nox -s generate # or: uv run python scripts/gen_docs.py
uv run python scripts/gen_docs.py --check # what CI runs: fails if they are stale
Docstrings use the Google style. Sphinx roles such as :class:`~pyxaf.raw.RawRecord` and simple
reST tables are converted to Markdown for the site by scripts/griffe_rst.py; prefer plain
Markdown (backticks, pipe tables) in new docstrings.
Examples in the guide should run as written. To try them without a real auditfile, generate synthetic files with the test-suite generator:
import sys
sys.path.insert(0, "tests")
import xafgen
open("2024.xaf", "wb").write(xafgen.write("4.0")) # also "3.2", "3.1", "CLAIR2", "ADF", ...
Citing¶
If you use pyxaf in research or audit work, please cite it using the metadata in CITATION.cff.