Quickstart#
Here’s how you would set up a conftest.py
in the root of your
project such that running pytest would check examples in your project’s source code
and Sphinx source. Python code-block
and doctest
examples will be checked:
from doctest import ELLIPSIS
from sybil import Sybil
from sybil.parsers.rest import DocTestParser, PythonCodeBlockParser
pytest_collect_file = Sybil(
parsers=[
DocTestParser(optionflags=ELLIPSIS),
PythonCodeBlockParser(),
],
patterns=['*.rst', '*.py'],
).pytest()
You’ll also want to disable pytest’s own doctest plugin by putting this in your pytest config:
[pytest]
addopts = -p no:doctest
An example of a documentation source file that could be checked using the above configuration is shown below:
Sample Documentation
====================
Let's put something in the Sybil document's namespace:
.. invisible-code-block: python
remember_me = b'see how namespaces work?'
Suppose we define a function, convoluted and pointless but shows stuff nicely:
.. code-block:: python
import sys
def prefix_and_print(message):
print('prefix:', message.decode('ascii'))
Now we can use a doctest REPL to show it in action:
>>> prefix_and_print(remember_me)
prefix: see how namespaces work?
The namespace carries across from example to example, no matter what parser:
>>> remember_me
b'see how namespaces work?'