{"id":14954,"library":"sybil-extras","title":"Sybil Extras","description":"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.","status":"active","version":"2026.3.1.6","language":"en","source_language":"en","source_url":"https://github.com/adamtheturtle/sybil-extras","tags":["documentation testing","pytest","sphinx","mypy","docutils","rst","myst"],"install":[{"cmd":"pip install sybil-extras","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency, sybil-extras extends its functionality.","package":"sybil","optional":false},{"reason":"Required for reStructuredText parsing, particularly for the `DOCUTILS_RST` parser.","package":"docutils","optional":true},{"reason":"Likely required for features related to Sphinx, such as Jinja2 support within RST.","package":"sphinx","optional":true},{"reason":"Required for integrating MyPy documentation testing.","package":"mypy","optional":true}],"imports":[{"note":"Imports the specialized reStructuredText parser from sybil-extras.","symbol":"DOCUTILS_RST","correct":"from sybil_extras.parsers.rst import DOCUTILS_RST"},{"note":"Imports the MyST parser for MyPy documentation. Path inferred.","symbol":"mypy_docs","correct":"from sybil_extras.parsers.myst import mypy_docs"}],"quickstart":{"code":"import pytest\nfrom sybil import Sybil\nfrom sybil_extras.parsers.rst import DOCUTILS_RST\n\nREADME = Sybil(\n    parsers=[DOCUTILS_RST], # Example using a sybil-extras parser\n    patterns=[\"*.rst\"],\n    fixtures=[\"tmp_path\"],\n)\n\n@pytest.mark.parametrize(\"sybil\", [README], ids=str)\ndef test_documentation(sybil):\n    sybil.run()\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"<2026.03.01.1"},{"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.","message":"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.","severity":"breaking","affected_versions":"<2026.03.01.3"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`).","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.","error":"ImportError: cannot import name 'DOCUTILS_RST' from 'sybil_extras.parsers.rst'"},{"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.","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.","error":"sybil.exceptions.SybilError: Error running example: Command failed (exit code ...)"}],"ecosystem":"pypi"}