TST: use sybil for doctests

[hagenw]

Similar to audeering/audinterface#178 we switch to use sybil for doctests.

This has several motivations:

• separate testing and building the documentation
• remove dependency on jupyter-sphinx (large dependencies, not well maintained)
• remove dependency on pytest-doctestplus (slow in adopting to newer pytest versions)
• write expected results of code blocks as part of the usage documentation
• allow to use pytest fixtures inside doctests

Update "Usage" section

Updated "Developer guide" section

Updated "Legacy backends" section

In the developer guide, I replaced the usage of shelve by pickle as the previous implementation worked under Linux, but not under MacOS (where it was not tested before).

Summary by Sourcery

Switch to sybil for doctests to separate testing from documentation building, remove large and outdated dependencies, and enhance testing capabilities with pytest fixtures.

Enhancements:

• Allow the use of pytest fixtures inside doctests.

Documentation:

• Update the 'Usage', 'Developer guide', and 'Legacy backends' sections to reflect the new testing approach and remove outdated references.

Tests:

• Switch to using sybil for collecting and running doctests, replacing pytest-doctestplus.

Chores:

• Remove dependencies on jupyter-sphinx and pytest-doctestplus due to maintenance and compatibility issues.

[sourcery-ai]

Reviewer's Guide by Sourcery

This PR switches the project's doctest implementation from pytest-doctestplus to sybil. The change involves restructuring how doctests are collected and executed, introducing pytest fixtures for test setup, and updating the documentation infrastructure. The implementation removes dependencies on jupyter-sphinx and pytest-doctestplus while maintaining test coverage.

Class diagram for updated testing infrastructure

classDiagram
    class Sybil {
        +pytest_collect_file
    }
    class DocTestParser {
        +optionflags: ELLIPSIS
    }
    class PythonCodeBlockParser
    class SkipParser
    class FileSystem {
        +opened: bool
    }
    class Versioned {
        +put_archive()
        +put_file()
        +get_file()
        +date()
        +owner()
    }
    class Unversioned {
        +put_file()
        +put_archive()
        +get_file()
    }
    class BackendError
    class Minio {
        +create()
    }
    Sybil --> DocTestParser
    Sybil --> PythonCodeBlockParser
    Sybil --> SkipParser
    Versioned --> FileSystem
    Unversioned --> FileSystem
    Minio --> FileSystem
    BackendError --> FileSystem
    note for Sybil "Sybil is used for collecting and running doctests"
    note for FileSystem "FileSystem backend is used in doctests"

Loading

File-Level Changes

Change	Details	Files
Implemented sybil-based doctest collection and execution system	Added new pytest fixtures for filesystem, date mocking, and owner mocking Created a Sybil configuration for collecting and parsing doctests Removed pytest-doctestplus specific configurations Added support for pytest fixtures in doctests	audbackend/core/conftest.py docs/conftest.py pyproject.toml
Refactored doctest examples across the codebase	Updated doctest setup code to use new fixtures Simplified test initialization in docstrings Made doctest examples more consistent across files Fixed path handling in test cases to use proper temporary directories	audbackend/core/interface/versioned.py audbackend/core/interface/unversioned.py audbackend/core/interface/base.py audbackend/core/interface/maven.py audbackend/core/errors.py audbackend/core/utils.py audbackend/core/backend/minio.py
Updated project dependencies and documentation setup	Removed jupyter-sphinx dependency Removed pytest-doctestplus dependency Added sybil as a test requirement Updated documentation configuration	docs/requirements.txt tests/requirements.txt docs/conf.py

---

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.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a 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. You can also use
  this command to specify where the summary should be inserted.

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.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.0%. Comparing base (b8d71ac) to head (a185e8a).
Report is 1 commits behind head on main.

Additional details and impacted files

Files with missing lines	Coverage Δ
audbackend/core/backend/minio.py	100.0% <ø> (ø)
audbackend/core/conftest.py	100.0% <100.0%> (ø)
audbackend/core/errors.py	100.0% <ø> (ø)
audbackend/core/interface/base.py	100.0% <ø> (ø)
audbackend/core/interface/maven.py	100.0% <ø> (ø)
audbackend/core/interface/unversioned.py	100.0% <ø> (ø)
audbackend/core/interface/versioned.py	100.0% <ø> (ø)
audbackend/core/utils.py	100.0% <ø> (ø)

[sourcery-ai]

Hey @hagenw - I've reviewed your changes and they look great!

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[ChristianGeng]

Review

Mainly the doctests are refactores to sybil.
I have reviewed structural changes to the testing process before - test identification was not 100% coherent with our previous approach.

Apart from that I have skimmed over the text , I did not find any flaws.

I also build the documentation, and it builds without errors.

So I would think approval is safe.