Developer Handbook

This document serves as the developer handbook, contribution guide, and architectural specification for asciidoctest.

We warmly welcome contributions of all kinds! Whether you are fixing a bug, adding new features, improving documentation, or proposing design enhancements, this handbook will guide you through our codebase architecture, testing conventions, and contribution workflows. Please review our Security Policy before running untrusted code blocks during local development.

Codebase Architecture

asciidoctest extracts and verifies code blocks from AsciiDoc (.adoc) files and Python docstrings.

Component Overview

graph TD
    A[Source Files: .adoc, .py, Modules] --> B[pytest_plugin / unittest_integration / docstring_extractor]
    B --> C[parser.py]
    C --> D[asciidoctrine / asciidocstring]
    D --> E[TestBlock List + Section IDs]
    E --> F[runner.py]
    F --> G[CustomDocTestRunner / exec]

parser.py: Extracts test blocks using asciidoctrine (with preprocess_directives=False by default to tolerate illustrative includes) and asciidocstring (for Python docstrings). Tracks top-level section boundaries via SafeTestBlockExtractorVisitor, parses marker attributes (test, shared, reset), and extracts named context scopes (shared="<name>"). Also statically discovers docstrings in Python source files via find_docstrings_in_py_file.
runner.py: Coordinates execution across interactive REPL blocks and non-interactive script blocks. Enforces namespace scoping, automatic section boundary resets, explicit reset directives, and named context state maps.
docstring_extractor.py: Implements the direct programmatic API extract_and_run_docstring_tests to discover, extract, and execute doctests from Python files, directories, or loaded modules with per-symbol scope isolation.
pytest_plugin.py: Discovers files statically, collects docstrings from Python modules without executing code during discovery, and handles test execution and error formatting for pytest.
unittest_integration.py: Wraps test collection and execution in standard library unittest adapters (DocFileSuite and DocTestSuite).

Testing and Coverage

tests/test_runner.py: Tests runner mechanics and state persistence.
tests/test_scoping.py: Tests named context scopes and explicit reset markers.
tests/test_section_scoping.py: Tests top-level AST section boundary resets.
tests/test_parser_includes.py: Tests tolerant illustrative include directive handling (preprocess_directives=False).
tests/test_docstring_extraction.py: Tests direct Python docstring extraction across files, directories, and modules.
tests/test_plugin.py: Validates basic pytest collection.
tests/test_plugin_coverage.py: Tests error boundaries and collection failures.
tests/test_unittest_integration.py: Tests unittest adapters.
tests/test_footnotes.py: Verifies footnote compatibility.

Coverage Measurement

$ .venv/bin/coverage run -m pytest
$ .venv/bin/coverage report -m

Pre-Release Checklist

1. Dependency Audit

☐ Verify that constraints in pyproject.toml are correctly aligned with the latest stable dependency releases.
☐ Ensure asciidocstring points to stable pre-release/release versions (e.g. >=0.1.0a2), avoiding premature or yanked releases.

2. Code Quality and Style

☐ Format code using Ruff code style checker (ruff check and ruff format).
☐ Run static type checking via mypy to ensure type-safety across all modules.

3. Verification Suite

☐ Install the package in editable mode with test and documentation dependencies:
```
$ .venv/bin/pip install -e ".[test,docs]"
```
☐ Run the complete test suite:
```
$ .venv/bin/pytest
```
☐ Measure code coverage and confirm that coverage remains above 95% total:
```
$ .venv/bin/coverage run -m pytest
$ .venv/bin/coverage report
```

4. Documentation Check

☐ Confirm that all examples inside README.adoc pass successfully under our self-verifying test suite.
☐ Review SECURITY.adoc and docs/security.adoc to ensure supported versions and reporting guidelines are up to date.
☐ Update CHANGELOG.adoc to catalog the latest changes, additions, and fixed bugs under the appropriate release version header.

5. Publishing Preparation

☐ Update the version field in pyproject.toml.
☐ Run build checks to generate clean source and wheel distributions:
```
$ .venv/bin/python3 -m build
```