Developer Handbook

This document describes the codebase architecture, testing conventions, and development workflows for asciidoctest.

Please review the 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 ignore illustrative includes) and asciidocstring (for Python docstrings). Tracks section boundaries, 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 script blocks. Enforces namespace scoping, section boundary resets, explicit reset directives, and named context state maps.
docstring_extractor.py: Implements the programmatic APIs run_adoc_tests and extract_and_run_docstring_tests to discover, extract, and execute doctests from .adoc files, .py files, directories, or loaded modules with per-symbol scope isolation.
pytest_plugin.py: Discovers files statically, collects docstrings from Python modules without executing module 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 AST section boundary resets.
tests/test_parser_includes.py: Tests illustrative include directive handling (preprocess_directives=False).
tests/test_docstring_extraction.py: Tests Python docstring extraction across files, directories, and modules.
tests/test_api.py: Tests programmatic runner API (run_adoc_tests) and fail_fast behavior.
tests/integration/: Tests API consumer workflows and end-to-end execution patterns.
tests/test_plugin.py: Validates pytest collection.
tests/test_plugin_collision.py: Tests module name isolation for same-named files across directories.
tests/test_plugin_coverage.py: Tests error boundaries and collection edge cases.
tests/test_unittest_integration.py: Tests unittest adapters.
tests/test_footnotes.py: Verifies footnote compatibility.

Development Commands

Using Hatch:

hatch run test          # Run test suite with coverage
hatch run cov-report    # Display coverage report
hatch run lint          # Run ruff check
hatch run format        # Check ruff formatting
hatch run format-fix    # Apply ruff formatting
hatch run typecheck     # Run mypy in strict mode
hatch run docs-build    # Build Sphinx documentation
hatch run docs-serve    # Serve built HTML documentation locally

Pre-Release Checklist

1. Dependency Audit

☐ Verify that constraints in pyproject.toml match expected dependency versions.
☐ Verify that pylock.toml is up to date.

2. Code Quality and Style

☐ Format code using Ruff (hatch run format or ruff check / ruff format).
☐ Run static type checking via mypy in strict mode (hatch run typecheck or mypy --strict asciidoctest).

3. Verification Suite

☐ Run the test suite:
```
hatch run test
```
☐ Verify code coverage meets the 97% requirement:
```
hatch run cov-report
```

4. Documentation Check

☐ Confirm that examples in README.adoc and documentation files pass during test execution.
☐ Review SECURITY.adoc and docs/security.adoc to ensure supported versions and reporting guidelines are current.
☐ Update CHANGELOG.adoc and docs/changelog.adoc with release notes for the target version.

5. Publishing Preparation

☐ Update the version field in pyproject.toml.
☐ Build distribution packages:
```
python -m build
```

< Executable State Models | Security Policy >