Merge #1124

1124: Resolve remaining doctests, enable doctest in CI r=hgrecco a=clarkgwillison - [x] Closes #1115 - [x] Executed ``black -t py36 . && isort -rc . && flake8`` with no errors - [x] The change is fully covered by automated unit tests - [x] Documented in docs/ as appropriate - [x] Added an entry to the CHANGES file This PR pushes off fixing the `get_compatible_units(..., group_or_system='...')` feature mentioned in #1115, removing references to it from the docs for now. It also enables doctests in CI now that all remaining doctests are passing Co-authored-by: Clark Willison <clarkgwillison@gmail.com>
hgrecco · Jul 13, 2020 · b6e1811 · b6e1811
2 parents b596887 + 1da80f4
commit b6e1811
Show file tree

Hide file tree

Showing 8 changed files with 35 additions and 31 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -75,6 +75,7 @@ script:
  - if [[ $PANDAS == 0 && $LINT == 0 && $DOCS == 0 ]]; then python -bb -m pytest $TEST_OPTS; fi
  - if [[ $LINT == 1 ]]; then black -t py36 --check . && isort -rc -c . && flake8; fi
  - if [[ $DOCS == 1 ]]; then PYTHONPATH=$PWD sphinx-build -n -j auto -b html -d build/doctrees docs build/html; fi
+ - if [[ $DOCS == 1 ]]; then PYTHONPATH=$PWD sphinx-build -a -j auto -b doctest -d build/doctrees docs build/doctest; fi
  - if [[ $LINT == 0 && $DOCS == 0 ]]; then coverage report -m; fi
 
 after_success:

diff --git a/CHANGES b/CHANGES
@@ -5,7 +5,7 @@ Pint Changelog
 -----------------
 
 - Implement Dask collection interface to support Pint Quantity wrapped Dask arrays.
-
+- Started automatically testing examples in the documentation
 
 0.14 (2020-07-01)
 -----------------

diff --git a/docs/conf.py b/docs/conf.py
@@ -321,3 +321,20 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"http://docs.python.org/": None}
+
+# -- Doctest configuration -----------------------------------------------------
+
+# fill a dictionary with package names that may be missing
+# this is checked by :skipif: clauses in certain doctests that rely
+# on optional dependencies
+doctest_global_setup = """
+from importlib.util import find_spec
+
+not_installed = {
+ pkg_name: find_spec(pkg_name) is None
+ for pkg_name in [
+ 'uncertainties',
+ 'serialize',
+ ]
+}
+"""
diff --git a/docs/measurement.rst b/docs/measurement.rst
@@ -7,6 +7,7 @@ Using Measurements
 Measurements are the combination of two quantities: the mean value and the error (or uncertainty). The easiest ways to generate a measurement object is from a quantity using the `plus_minus` operator.
 
 .. doctest::
+ :skipif: not_installed['uncertainties']
 
  >>> import numpy as np
  >>> from pint import UnitRegistry
@@ -15,16 +16,10 @@ Measurements are the combination of two quantities: the mean value and the error
  >>> print(book_length)
  (20.0 +/- 2.0) centimeter
 
-.. testsetup:: *
-
- import numpy as np
- from pint import UnitRegistry
- ureg = UnitRegistry()
- Q_ = ureg.Quantity
-
 You can inspect the mean value, the absolute error and the relative error:
 
 .. doctest::
+ :skipif: not_installed['uncertainties']
 
  >>> print(book_length.value)
  20.0 centimeter
@@ -36,6 +31,7 @@ You can inspect the mean value, the absolute error and the relative error:
 You can also create a Measurement object giving the relative error:
 
 .. doctest::
+ :skipif: not_installed['uncertainties']
 
  >>> book_length = (20. * ureg.centimeter).plus_minus(.1, relative=True)
  >>> print(book_length)
@@ -44,6 +40,7 @@ You can also create a Measurement object giving the relative error:
 Measurements support the same formatting codes as Quantity. For example, to pretty print a measurement with 2 decimal positions:
 
 .. doctest::
+ :skipif: not_installed['uncertainties']
 
  >>> print('{:.02fP}'.format(book_length))
  (20.00 ± 2.00) centimeter
@@ -52,6 +49,7 @@ Measurements support the same formatting codes as Quantity. For example, to pret
 Mathematical operations with Measurements, return new measurements following the `Propagation of uncertainty`_ rules.
 
 .. doctest::
+ :skipif: not_installed['uncertainties']
 
  >>> print(2 * book_length)
  (40 +/- 4) centimeter

diff --git a/docs/pint-pandas.ipynb b/docs/pint-pandas.ipynb
@@ -22,9 +22,13 @@
  "## Installation\n",
  "\n",
  "\n",
- "Pandas support is provided by `pint-pandas`. It is not available on PyPI yet, to install it use\n",
+ "Pandas support is provided by the `pint-pandas` package. To install it use either:\n",
  "```\n",
- "python -m pip install git+https://github.com/hgrecco/pint-pandas.git\n",
+ "python -m pip install pint-pandas\n",
+ "```\n",
+ "Or:\n",
+ "```\n",
+ "conda install -c conda-forge pint-pandas\n",
  "```"
  ]
  },

diff --git a/docs/serialization.rst b/docs/serialization.rst
@@ -98,6 +98,7 @@ numerical type such as `numpy.ndarray`).
 Using the serialize_ package you can load and read from multiple formats:
 
 .. doctest::
+ :skipif: not_installed['serialize']
 
  >>> from serialize import dump, load, register_class
  >>> register_class(ureg.Quantity, ureg.Quantity.to_tuple, ureg.Quantity.from_tuple)

diff --git a/docs/systems.rst b/docs/systems.rst
@@ -36,29 +36,11 @@ or more drastically to:
  >>> '{:.3f}'.format(q.to_base_units())
  '1.094 yard / second'
 
-.. warning:: In versions previous to 0.7 ``to_base_units`` returns quantities in the
+.. warning:: In versions previous to 0.7, ``to_base_units()`` returns quantities in the
  units of the definition files (which are called root units). For the definition file
- bundled with pint this is meter/gram/second. To get back this behaviour use ``to_root_units``,
+ bundled with pint this is meter/gram/second. To get back this behaviour use ``to_root_units()``,
  set ``ureg.system = None``
 
-
-You can also use system to narrow down the list of compatible units:
-
-.. doctest::
-
- >>> ureg.default_system = 'mks'
- >>> ureg.get_compatible_units('meter')
- frozenset({<Unit('light_year')>, <Unit('angstrom')>})
-
-or for imperial units:
-
-.. doctest::
-
- >>> ureg.default_system = 'imperial'
- >>> ureg.get_compatible_units('meter')
- frozenset({<Unit('thou')>, <Unit('league')>, <Unit('nautical_mile')>, <Unit('inch')>, <Unit('mile')>, <Unit('yard')>, <Unit('foot')>})
-
-
 You can check which unit systems are available:
 
 .. doctest::
@@ -71,7 +53,7 @@ Or which units are available within a particular system:
 .. doctest::
 
  >>> dir(ureg.sys.imperial)
- ['UK_hundredweight', 'UK_ton', 'acre_foot', 'cubic_foot', 'cubic_inch', 'cubic_yard', 'drachm', 'foot', 'grain', 'imperial_barrel', 'imperial_bushel', 'imperial_cup', 'imperial_fluid_drachm', 'imperial_fluid_ounce', 'imperial_gallon', 'imperial_gill', 'imperial_peck', 'imperial_pint', 'imperial_quart', 'inch', 'long_hunderweight', 'long_ton', 'mile', 'ounce', 'pound', 'quarter', 'short_hunderdweight', 'short_ton', 'square_foot', 'square_inch', 'square_mile', 'square_yard', 'stone', 'yard']
+ ['UK_force_ton', 'UK_hundredweight', ... 'cubic_foot', 'cubic_inch', ... 'thou', 'ton', 'yard']
 
 Notice that this give you the opportunity to choose within units with colliding names:
 

diff --git a/docs/tutorial.rst b/docs/tutorial.rst
@@ -393,6 +393,7 @@ syntax'_ for custom float representations. For example, scientific notation:
 Pint also supports the LaTeX siunitx package:
 
 .. doctest::
+ :skipif: not_installed['uncertainties']
 
  >>> accel = 1.3 * ureg['meter/second**2']
  >>> # siunitx Latex print