sybil
Skill126 starsChanged 9 months agoApache-2.0View on GitHub
Use Sybil for testing code examples in documentation and docstrings. Covers pytest integration, parsers, skip directives, and namespace management.
- Installs packages
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- claude-improve-configSkill
- docs-page-frontmatterSkill
- hypothesisSkill
- narwhalsSkill
- syrupySkill
- tachSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 107
Add to pyproject.toml to prevent conflicts:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Sybil Documentation Testing
Sybil validates code examples embedded in documentation and docstrings by parsing and executing them as part of normal test runs.
Official Documentation: https://sybil.readthedocs.io/en/latest/
Installation
pip install sybil[pytest]Pytest Integration
Configure in conftest.py. See pytest integration docs.
from sybil import Sybil
from sybil.parsers.markdown.codeblock import PythonCodeBlockParser
from sybil.parsers.markdown.skip import SkipParser
pytest_collect_file = Sybil(
parsers=[
SkipParser(),
PythonCodeBlockParser(),
],
patterns=["*.md", "**/*.py"],
).pytest()Sybil Parameters
See API reference.
| Parameter | Description |
parsers | Sequence of parser callables |
patterns | File glob patterns to include (e.g., ["*.md", "src/**/*.py"]) |
excludes | File glob patterns to exclude |
setup | Callable receiving namespace dict, called before each document |
teardown | Callable receiving namespace dict, called after each document |
fixtures | List of pytest fixture names to inject into namespace |
document_types | Map file extensions to Document classes |
Document Types
See API reference.
- Default: Parse entire file
PythonDocument: Import.pyfile as module, names available in namespacePythonDocStringDocument: Parse only docstrings from.pyfiles
from sybil.document import PythonDocStringDocument
pytest_collect_file = Sybil(
parsers=[...],
patterns=["src/**/*.py"],
document_types={".py": PythonDocStringDocument},
).pytest()Fixtures
import pytest
from sybil import Sybil
@pytest.fixture
def my_fixture():
return {"key": "value"}
pytest_collect_file = Sybil(
parsers=[...],
patterns=["*.md"],
fixtures=["my_fixture"], # Available in document namespace
).pytest()Setup/Teardown
def sybil_setup(namespace):
namespace["helper"] = lambda x: x * 2
def sybil_teardown(namespace):
pass # Cleanup if needed
pytest_collect_file = Sybil(
parsers=[...],
setup=sybil_setup,
teardown=sybil_teardown,
).pytest()Disable pytest's Built-in Doctest
Add to pyproject.toml to prevent conflicts:
[tool.pytest.ini_options]
addopts = "-p no:doctest"Markdown Parsers
from sybil.parsers.markdown.codeblock import PythonCodeBlockParser, CodeBlockParser
from sybil.parsers.markdown.skip import SkipParser
from sybil.parsers.markdown.clear import ClearNamespaceParserSkip Directives
See skip directive docs.
SkipParser must come before other parsers to handle skip directives.
<!-- skip: next -->
```python
# This example is skipped
```<!-- skip: next "reason for skipping" --># Skipped and reported as skipped test with reason<!-- skip: start --># Multiple examples# All skipped<!-- skip: end --><!-- skip: next if(condition_var) --># Conditionally skipped based on namespace variable## Invisible Code Blocks
Setup code that doesn't render in documentation. See [invisible code blocks docs](https://sybil.readthedocs.io/en/latest/markdown.html#invisible-code-blocks).
```markdown
<!-- invisible-code-block: python
setup_var = "hidden setup"
-->Clear Namespace
Reset the document namespace for isolation. See clear namespace docs.
<!-- clear-namespace -->Custom Evaluators
See evaluators API.
from sybil.parsers.markdown.codeblock import CodeBlockParser
from sybil.evaluators.python import PythonEvaluator
# Custom evaluator with future imports
evaluator = PythonEvaluator(future_imports=["annotations"])
parser = CodeBlockParser(language="python", evaluator=evaluator)Running Sybil Tests
Sybil tests are collected like regular pytest tests. To run only Sybil tests:
# Run tests from specific directory containing documented code
pytest src/mypackage/ -v
# Exclude regular tests, only run documentation examples
pytest docs/ -vTo exclude Sybil tests from regular test runs, use pytest's --ignore flag or configure addopts in pyproject.toml.
Example: Complete conftest.py
"""Sybil configuration for docstring testing."""
from sybil import Sybil
from sybil.document import PythonDocStringDocument
from sybil.evaluators.python import PythonEvaluator
from sybil.parsers.markdown.codeblock import CodeBlockParser
from sybil.parsers.markdown.skip import SkipParser
import mypackage
def sybil_setup(namespace):
"""Pre-populate namespace for all examples."""
namespace["pkg"] = mypackage
def sybil_teardown(namespace):
"""Cleanup after document."""
pass
pytest_collect_file = Sybil(
parsers=[
SkipParser(),
CodeBlockParser(language="python", evaluator=PythonEvaluator()),
CodeBlockParser(language="py", evaluator=PythonEvaluator()),
],
patterns=["src/mypackage/**/*.py"],
document_types={".py": PythonDocStringDocument},
setup=sybil_setup,
teardown=sybil_teardown,
excludes=[
"**/tests/**",
"**/_internal/**",
],
).pytest()Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

