Quickstart

Sybil is installed as a standard Python package in whatever way works best for you. If you’re using it with pytest, you should install it with the pytest extra, to ensure you have compatible versions:

pip install sybil[pytest]

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?'