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 <[email protected]>
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