sybil

What problem does it solve?

Sybil automates testing of code examples embedded in documentation and docstrings by parsing and executing them as part of normal test runs.

Core Features & Use Cases

• Pytest integration: Integrates with pytest to collect and run code blocks from Markdown and Python docstrings during test runs.
• Parsers and skip directives: Supports multiple Markdown codeblock parsers and skip directives to selectively run examples.
• Namespace management: Allows pre-populating a namespace and teardown between examples to ensure isolation.
• Documentation reliability: Keeps documentation aligned with implementation, catching drift and broken examples early.

Use cases include validating documentation snippets in API docs, tutorials, and inline docstrings to keep documentation accurate.

Quick Start

Install Sybil and integrate with pytest to start testing documentation samples. Example commands:

• pip install 'sybil[pytest]'
• Create a pytest configuration that uses Sybil, for example:
• from sybil import Sybil
• from sybil.parsers.markdown.codeblock import PythonCodeBlockParser
• pytest_collect_file = Sybil(parsers=[PythonCodeBlockParser()], patterns=["docs/**/*.md"]).pytest()
• Run pytest to execute the documentation examples.