Use sybil for doctests

[hagenw]

Use sybil instead of jupyter-sphinx for better separation of testing and building the documentation.

[sourcery-ai]

Reviewer's Guide

Replace jupyter-sphinx-based documentation execution with Sybil-powered doctest and code block testing, wiring it into pytest and adding fixtures to control audmodel configuration and execution environment while updating dependencies accordingly.

Sequence diagram for Sybil-based doctest collection with pytest

sequenceDiagram
    participant Pytest
    participant SybilCollection
    participant Sybil_usage as Sybil_usage_rst
    participant Sybil_config as Sybil_configuration_rst
    participant Fixture_run_tmp as run_in_tmpdir
    participant Fixture_reset_cfg as reset_config
    participant Fixture_default_cfg as default_configuration
    participant AudConfig as audmodel.config

    Pytest->>SybilCollection: pytest_collect_file
    SybilCollection->>Sybil_usage: pytest()
    activate Sybil_usage
    Sybil_usage->>Fixture_run_tmp: run_in_tmpdir
    Fixture_run_tmp-->>Sybil_usage: tmpdir context
    Sybil_usage->>Fixture_reset_cfg: reset_config
    Fixture_reset_cfg-->>Sybil_usage: config snapshot
    Sybil_usage-->>SybilCollection: execute doctests in usage.rst
    deactivate Sybil_usage

    SybilCollection->>Sybil_config: pytest()
    activate Sybil_config
    Sybil_config->>Fixture_default_cfg: default_configuration
    Fixture_default_cfg->>AudConfig: load_configuration_file
    AudConfig-->>Fixture_default_cfg: default values
    Sybil_config-->>SybilCollection: execute doctests in configuration.rst
    deactivate Sybil_config

    SybilCollection-->>Pytest: report doctest results

Loading

File-Level Changes

Change	Details	Files
Switch documentation execution/testing from jupyter-sphinx to Sybil-based doctest/code block collection integrated with pytest.	Remove jupyter-sphinx from development dependencies and Sphinx extensions. Add sybil as a development dependency and configure it for rst doctests and Python code blocks in docs. Introduce a pytest-based Sybil collection that gathers tests from usage.rst and configuration.rst with appropriate parsers.	pyproject.toml docs/conf.py docs/conftest.py docs/usage.rst docs/configuration.rst
Add fixture and configuration infrastructure to ensure documentation tests run in isolated, reproducible environments and with consistent audmodel config state.	Create fixtures to run documentation files in a temporary working directory for the duration of each module. Add fixtures to snapshot and restore audmodel configuration, including handling AUDMODEL_CACHE_ROOT environment overrides. Load default configuration from the global config file to provide deterministic defaults for configuration.rst doctests and restore prior state afterward.	docs/conftest.py
Align pytest configuration with documentation testing via Sybil.	Stop ignoring the docs/ directory in pytest addopts so documentation tests are collected. Keep existing misc/ ignore rule while allowing Sybil-collected doctests to run as part of the main test suite.	pyproject.toml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.