1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
.. currentmodule:: sybil
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
Linting and checking examples
-----------------------------
If you wish to perform linting of examples in addition to checking that they are correct,
you will need to parse each documentation file once for linting and once for checking.
This can be done by having one :class:`Sybil` to do the linting and another :class:`Sybil`
to do the checking.
Given documentation that looks like this:
.. literalinclude:: examples/linting_and_checking/index.rst
Then the following configuration in a ``conftest.py`` could be used to ensure all
your examples are both correct and lint-free:
.. literalinclude:: examples/linting_and_checking/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>`.
|
