Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

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