Merge pull request #201 from scipy/tweak_readme

DOC: minor README tweaks

Author: ev-br

README.md

@@ -151,7 +151,7 @@ $ pytest --pyargs <your-package> --doctest-modules --doctest-collect=api
 See [More fine-grained control](#more-fine-grained-control) section
 for details on how to customize the behavior.
 
-**NOTE ** Currently, `pytest --doctest-modules` only collects doctests and skips
+**NOTE** Currently, `pytest --doctest-modules` only collects doctests and skips
 'regular' unit tests. This differs from the vanilla `pytest` behavior, which collects
 both doctests and unit tests.
 The behavior will change in a future version: `scipy-doctest==2.0` **will change the
@@ -318,7 +318,7 @@ $ spin smoke-tutorials   # ReST user guide tutorials
 
 Here is a (non-exhaustive) list of possible gotchas:
 
-- _In-place development builds_.
+#### _In-place development builds_.
 
 Some tools (looking at you `meson-python`) simulate in-place builds with a
 `build-install` directory. If this directory is located under the project root,
@@ -342,10 +342,10 @@ If push really comes to shove, you may try using the magic env variable:
 however the need usually indicates an issue with the package itself.
 (see [gh-107](https://github.com/scipy/scipy_doctest/pull/107) for an example).
 
-- _Optional dependencies are not that optional_
+#### _Optional dependencies are not that optional_
 
 If your package contains optional dependencies, doctests do not know about them
-being optional. So you either guard the imports in doctests (yikes!), or
+being optional. So you either guard the imports in doctests themselves (yikes!), or
 the collections fails if dependencies are not available.
 
 The solution is to explicitly `--ignore` the paths to modules with optionals.
@@ -361,7 +361,7 @@ Note that installed packages are no different:
 $ pytest --pyargs scipy --doctest-modules --ignore=/path/to/installed/scipy/_lib
 ```
 
-- _Doctest collection strategies_
+#### _Doctest collection strategies_
 
 The default collection strategy follows `doctest` module and `pytest`. This leads
 to duplicates if your package has the split between public and \_private modules,
@@ -371,19 +371,19 @@ objects will be collected.
 
 The decision on what is public is as follows: an object is public iff
 
-- it is included into the `__all__` list of a public module;
-- the name of the object does not have a leading underscore;
-- the name of the module from which the object is collected does not have
+  - it is included into the `__all__` list of a public module;
+  - the name of the object does not have a leading underscore;
+  - the name of the module from which the object is collected does not have
   a leading underscore.
 
 Consider an example: `scipy.linalg.det` is defined in `scipy/linalg/_basic.py`,
 so it is collected twice, from `_basic.py` and from `__init__.py`. The rule above
 leads to
 
-- `scipy.linalg._basic.det`, collected from `scipy/linalg/_basic.py`, is private.
-- `scipy.linalg.det`, collected from `scipy/linalg/__init__.py`, is public.
+  - `scipy.linalg._basic.det`, collected from `scipy/linalg/_basic.py`, is private.
+  - `scipy.linalg.det`, collected from `scipy/linalg/__init__.py`, is public.
 
-- _`pytest`'s assertion rewriting_
+#### _`pytest`'s assertion rewriting_
 
 In some rare cases you may need to either explicitly register the `scipy_doctest`
 package with the `pytest` assertion rewriting machinery, or ask it to avoid rewriting
@@ -395,31 +395,52 @@ In general, rewriting assertions is not very useful for doctests, as the
 output on error is fixed by the doctest machinery anyway. Therefore, we believe
 adding `--assert=plain` is reasonable.
 
+#### _Mixing strings and numbers_
+
+Generally, we aim to handle mixtures of strings and numeric data. Deeply nested data
+structures, however, may cause the checker to fall back to the vanilla `doctest` literal
+checking. For instance, `["value", 1/3]` will use the floating-point aware checker, and
+so will `{"value": 1/3, "other value": 2/3}` or `[(1, 2), (3, 4)]`; Meanwhile, nested
+dictionaries, `{"a": dict(value=1/3)}`, or lists of tuples with mixed entries,
+`[("a", 1/3), ("b", 2/3)]`, will currently fall back to vanilla `doctest` literal
+comparisons.
+
+We stress that no matter how tricky or deeply nested the output is, the worst case
+scenario is that the floating-point aware checker is not used. If you have a case where
+`doctest` works correctly and `scipy_doctest` does not, please report it as a bug.
+
+
 ## Prior art and related work
 
 - `pytest` provides some limited floating-point aware `NumericLiteralChecker`.
 
 - `pytest-doctestplus` plugin from the `AstroPy` project has similar goals.
   The package is well established and widely used. From a user perspective, main
   differences are: (i) `pytest-doctestplus` is more sensitive to formatting,
-  including whitespace---thus if numpy tweaks its output formatting, doctests
-  may start failing; (ii) there is still a need for `# doctest: +FLOAT_CMP`
+  including whitespace; (ii) there is still a need for `# doctest: +FLOAT_CMP`
   directives.
 
-  This project takes a different approach: in addition to plugging into `pytest`,
-  we closely follow the `doctest` API and implementation, which are naturally
-  way more stable then `pytest`.
+  This project takes a slightly different approach: we strive to make numeric comparisons
+  whitespace insensitive and automatic, without a need for explicit markup.  For rare cases
+  which require additional configuration, we either keep it in the tool (thus out of
+  reader-visible docstrings), or provide human-readable markers (hence `# may vary`
+  not `# doctest +SKIP`).
+  Furthermore, in addition to plugging into `pytest`, we provide an API layer which closely
+  follows the `doctest` API. Essentially all aspects of doctesting are user-configurable.
+
+- `xdoctest` package relies on a deeper rewrite of the standard-library `doctest`
+  functionality, and uses an AST-based analysis to parse code examples out of docstrings.
 
 - `NumPy` and `SciPy` were using modified doctesting in their `refguide-check` utilities.
-  These utilities are tightly coupled to their libraries, and have been reported
+  These utilities were tightly coupled to their libraries, and have been reported
   to be not easy to reason about, work with, and extend to other projects.
 
-  This project is mainly the core functionality of the modified
-  `refguide-check` doctesting, extracted to a separate package.
-  We believe having it separate simplifies both addressing the needs of these
-  two packages, and potential adoption by other projects.
+  This project is mainly the core functionality of the modified `refguide-check` doctesting,
+  extracted to a separate package. We believe having it separate simplifies both
+  addressing the needs of these two packages, and adoption by other projects.
+
 
-### Bug reports, feature requests and contributions
+## Bug reports, feature requests and contributions
 
 This package is work in progress. Contributions are most welcome!
 Please don't hesitate to open an issue in the tracker or send a pull request.