Skip to content

Commit 459919a

Browse files
committed
DOC: tweak the "prior art" comparisons
1 parent 1b3dff5 commit 459919a

File tree

1 file changed

+12
-6
lines changed

1 file changed

+12
-6
lines changed

README.md

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ $ pytest --pyargs <your-package> --doctest-modules --doctest-collect=api
151151
See [More fine-grained control](#more-fine-grained-control) section
152152
for details on how to customize the behavior.
153153

154-
**NOTE ** Currently, `pytest --doctest-modules` only collects doctests and skips
154+
**NOTE** Currently, `pytest --doctest-modules` only collects doctests and skips
155155
'regular' unit tests. This differs from the vanilla `pytest` behavior, which collects
156156
both doctests and unit tests.
157157
The behavior will change in a future version: `scipy-doctest==2.0` **will change the
@@ -402,13 +402,19 @@ adding `--assert=plain` is reasonable.
402402
- `pytest-doctestplus` plugin from the `AstroPy` project has similar goals.
403403
The package is well established and widely used. From a user perspective, main
404404
differences are: (i) `pytest-doctestplus` is more sensitive to formatting,
405-
including whitespace---thus if numpy tweaks its output formatting, doctests
406-
may start failing; (ii) there is still a need for `# doctest: +FLOAT_CMP`
405+
including whitespace; (ii) there is still a need for `# doctest: +FLOAT_CMP`
407406
directives.
408407

409-
This project takes a different approach: in addition to plugging into `pytest`,
410-
we closely follow the `doctest` API and implementation, which are naturally
411-
way more stable then `pytest`.
408+
This project takes a slightly different approach: we strive to make numeric comparisons
409+
whitespace insensitive and automatic, without a need for explicit markup. For rare cases
410+
which require additional configuration, we either keep it in the tool (thus out of
411+
reader-visible docstrings), or provide human-readable markers (hence `# may vary`
412+
not `# doctest +SKIP`).
413+
Furthermore, in addition to plugging into `pytest`, we provide an API layer which closely
414+
follows the `doctest` API. Essentially all aspects of doctesting are user-configurable.
415+
416+
- `xdoctest` package relies on a deeper rewrite of the standard-library `doctest`
417+
functionality, and uses an AST-based analysis to parse code examples out of docstrings.
412418

413419
- `NumPy` and `SciPy` were using modified doctesting in their `refguide-check` utilities.
414420
These utilities are tightly coupled to their libraries, and have been reported

0 commit comments

Comments
 (0)