Sybil Extras

2026.3.1.6 · active · verified Thu Apr 16

sybil-extras is a Python library that provides additional parsers and functionalities to Sybil, the documentation testing tool. It extends Sybil's capabilities to handle more complex documentation formats and integrations, such as MyPy documentation and advanced reStructuredText features. The library is actively maintained with frequent releases, currently at version 2026.3.1.6.

Common errors

```
ImportError: cannot import name 'DOCUTILS_RST' from 'sybil_extras.parsers.rst'
```
cause The `sybil-extras` library or its specific parsers were not correctly installed, or the import path is incorrect. It may also mean the optional dependency `docutils` is missing.

fix Ensure `sybil-extras` is installed (`pip install sybil-extras`) and that `docutils` is also installed (`pip install docutils`). Verify the import statement matches the library's structure (e.g., `from sybil_extras.parsers.rst import DOCUTILS_RST`).
```
sybil.exceptions.SybilError: Error running example: Command failed (exit code ...)
```
cause An example within your documentation failed to execute correctly, possibly due to a parsing issue introduced by `sybil-extras` (especially in older versions) or an error in the example code itself.

fix First, check the example code for correctness. If `DOCUTILS_RST` or `mypy_docs` are involved, consider updating `sybil-extras` to the latest version (>=2026.03.01.3 for RST issues, >=2026.03.01.1 for MyPy issues) and ensure all required dependencies are met. Inspect the full traceback for more specific details on the command that failed.

Warnings

gotcha Older versions of `sybil-extras` (prior to 2026.03.01.1) might have incorrectly applied `--example-workers 0` to all MyPy documentation examples, potentially causing unexpected behavior or errors if MyPy examples were not designed for single-worker execution.
Fix: Upgrade to `sybil-extras` version 2026.03.01.1 or later. Ensure your MyPy testing setup is compatible with current `mypy_docs` parser behavior.
breaking In versions prior to 2026.03.01.3, the `DOCUTILS_RST` parser could crash when encountering reStructuredText `include` directives or did not support Sphinx Jinja2 syntax within RST files.
Fix: Upgrade to `sybil-extras` version 2026.03.01.3 or newer to resolve crashes with `include` directives and enable Sphinx Jinja2 support. You may also need to update `docutils` and `sphinx` dependencies if issues persist.
gotcha Ensure all necessary underlying parsers (like `docutils` for `DOCUTILS_RST` or `mypy` for `mypy_docs`) are installed as optional dependencies. Missing these will lead to import errors or runtime failures when their respective parsers are used.
Fix: Install optional dependencies as needed, e.g., `pip install sybil-extras[rst]` or `pip install 'sybil-extras[mypy]'` if such extras are defined, or install the base packages directly: `pip install docutils sphinx mypy`.

Install

pip install sybil-extras Install latest version

Imports

DOCUTILS_RST
```
from sybil_extras.parsers.rst import DOCUTILS_RST
```
Imports the specialized reStructuredText parser from sybil-extras.
mypy_docs
```
from sybil_extras.parsers.myst import mypy_docs
```
Imports the MyST parser for MyPy documentation. Path inferred.

Quickstart

This quickstart demonstrates integrating a sybil-extras parser, `DOCUTILS_RST`, with `pytest` to test reStructuredText documentation. It sets up Sybil to discover and evaluate examples within .rst files.

import pytest
from sybil import Sybil
from sybil_extras.parsers.rst import DOCUTILS_RST

README = Sybil(
    parsers=[DOCUTILS_RST], # Example using a sybil-extras parser
    patterns=["*.rst"],
    fixtures=["tmp_path"],
)

@pytest.mark.parametrize("sybil", [README], ids=str)
def test_documentation(sybil):
    sybil.run()

view raw JSON →