Patterns of Use
===============

.. invisible-code-block: python

  from tests.helpers import check_tree

Several commons patterns of use for Sybil are covered here.

Documentation and source examples in Restructured Text
------------------------------------------------------

If your project looks like this::

    ├─docs/
    │ ├─conf.py
    │ └─index.rst
    ├─src/
    │ └─myproj/
    │   └─__init__.py
    ├─conftest.py
    ├─pytest.ini
    └─setup.py

.. --> tree

.. invisible-code-block: python

  check_tree(tree, 'examples/rest_text_rest_src')

And if your documentation looks like this:

.. literalinclude:: examples/rest_text_rest_src/docs/index.rst
  :language: rest

With your examples in source code looking like this:

.. literalinclude:: examples/rest_text_rest_src/src/myproj/__init__.py

Then the following configuration in a ``conftest.py`` will ensure all
your examples are correct:

.. literalinclude:: examples/rest_text_rest_src/conftest.py


Documentation in MyST and source examples in Restructured Text
--------------------------------------------------------------

If your project looks like this::

    ├─docs/
    │ ├─conf.py
    │ └─index.md
    ├─src/
    │ └─myproj/
    │   └─__init__.py
    ├─conftest.py
    ├─pytest.ini
    └─setup.py

.. --> tree

.. invisible-code-block: python

  check_tree(tree, 'examples/myst_text_rest_src')

And if your documentation looks like this:

.. literalinclude:: examples/myst_text_rest_src/docs/index.md
  :language: markdown

With your examples in source code looking like this:

.. literalinclude:: examples/myst_text_rest_src/src/myproj/__init__.py

Then the following configuration in a ``conftest.py`` will ensure all
your examples are correct:

.. literalinclude:: examples/myst_text_rest_src/conftest.py

.. _migrating-from-sphinx.ext.doctest:

Migrating from sphinx.ext.doctest
---------------------------------

Sybil currently has partial support for
:external+sphinx:doc:`sphinx.ext.doctest <usage/extensions/doctest>`.
The list below shows how to approach migrating or supporting the various
directives from ``sphinx.ext.doctest``. Adding further support won't be hard,
so if anything is missing that's holding you back, please open an issue on `GitHub`__.
After that, it's mainly left to stop running ``make doctest``!

__ https://github.com/simplistix/sybil/issues

- :rst:dir:`testsetup` can be replaced with :ref:`invisible-code-block <codeblock-parser>`.

- :rst:dir:`testcleanup` can be replaced with :ref:`invisible-code-block <codeblock-parser>`.

- :rst:dir:`doctest` is supported using the :class:`~sybil.parsers.rest.DocTestDirectiveParser`
  as described in the :ref:`doctest-parser` section.
  Some of the options aren't supported, but their behaviour can be replaced by preceding the
  ``doctest`` with a :ref:`skip <skip-parser>` directive.

- :rst:dir:`testcode` and :rst:dir:`testoutput` would need parsers and evaluators to be written,
  however, they could probably just be replaced with a :ref:`doctest-parser` block.

- ``groups`` aren't supported, but you can achieve test isolation using
  :ref:`clear-namespace <clear-namespace>`.
