Merge #1132

1132: Some rewriting and rearranging of docs, including more (and fixed) links r=hgrecco a=clarkgwillison

- [x] Addresses (but not closes) #972
- [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
- [ ] Added an entry to the CHANGES file

This PR started with small fixes to links (small syntax errors that were causing links not to render in Sphinx) and some grammar changes, but ended up redoing much of the tutorial page.

The main commit is 3a1d475, which moves a good portion of the "parsing strings" section of the tutorial to a new page dedicated to explaining all the ways to define a `Quantity()` in Pint. Theory here is a slightly shorter tutorial with good links to more in-depth coverage will be more helpful to new users and old, but that's just a theory.

This PR also removes the testsuite from the developer reference, though it doesn't fix any of the other rendering issues in there.

Feedback humbly solicited.

Co-authored-by: Clark Willison <clarkgwillison@gmail.com>

docs/conf.py

@@ -33,6 +33,7 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
  "sphinx.ext.autodoc",
+ "sphinx.ext.autosectionlabel",
  "sphinx.ext.doctest",
  "sphinx.ext.intersphinx",
  "sphinx.ext.coverage",

docs/contexts.rst

@@ -1,4 +1,3 @@
-.. _contexts:
 
 Contexts
 ========

docs/defining-quantities.rst

@@ -0,0 +1,142 @@
+Defining Quantities
+===================
+
+A quantity in Pint is the product of a unit and a magnitude.
+
+Pint supports several different ways of defining physical quantities, including
+a powerful string parsing system. These methods are largely interchangeable,
+though you may **need** to use the constructor form under certain circumstances
+(see :doc:`nonmult` for an example of where the constructor form is required).
+
+By multiplication
+-----------------
+
+If you've read the :ref:`Tutorial`, you're already familiar with defining a
+quantity by multiplying a ``Unit()`` and a scalar:
+
+.. doctest::
+
+ >>> from pint import UnitRegistry
+ >>> ureg = UnitRegistry()
+ >>> ureg.meter
+ <Unit('meter')>
+ >>> 30.0 * ureg.meter
+ <Quantity(30.0, 'meter')>
+
+This works to build up complex units as well:
+
+.. doctest::
+
+ >>> 9.8 * ureg.meter / ureg.second**2
+ <Quantity(9.8, 'meter / second ** 2')>
+
+
+Using the constructor
+---------------------
+
+In some cases it is useful to define :class:`Quantity() <pint.quantity.Quantity>`
+objects using it's class constructor. Using the constructor allows you to
+specify the units and magnitude separately.
+
+We typically abbreviate that constructor as `Q_` to make it's usage less verbose:
+
+.. doctest::
+
+ >>> Q_ = ureg.Quantity
+ >>> Q_(1.78, ureg.meter)
+ <Quantity(1.78, 'meter')>
+
+As you can see below, the multiplication and constructor methods should produce
+the same results:
+
+.. doctest::
+
+ >>> Q_(30.0, ureg.meter) == 30.0 * ureg.meter
+ True
+ >>> Q_(9.8, ureg.meter / ureg.second**2)
+ <Quantity(9.8, 'meter / second ** 2')>
+
+
+Using string parsing
+--------------------
+
+Pint includes a powerful parser for detecting magnitudes and units (with or
+without prefixes) in strings. Calling the ``UnitRegistry()`` directly
+invokes the parsing function:
+
+.. doctest::
+
+ >>> 30.0 * ureg('meter')
+ <Quantity(30.0, 'meter')>
+ >>> ureg('30.0 meters')
+ <Quantity(30.0, 'meter')>
+ >>> ureg('3000cm').to('meters')
+ <Quantity(30.0, 'meter')>
+
+The parsing function is also available to the ``Quantity()`` constructor and
+the various ``.to()`` methods:
+
+.. doctest::
+
+ >>> Q_('30.0 meters')
+ <Quantity(30.0, 'meter')>
+ >>> Q_(30.0, 'meter')
+ <Quantity(30.0, 'meter')>
+ >>> Q_('3000.0cm').to('meter')
+ <Quantity(30.0, 'meter')>
+
+Or as a standalone method on the ``UnitRegistry``:
+
+.. doctest::
+
+ >>> 2.54 * ureg.parse_expression('centimeter')
+ <Quantity(2.54, 'centimeter')>
+
+It is fairly good at detecting compound units:
+
+.. doctest::
+
+ >>> g = ureg('9.8 meters/second**2')
+ >>> g
+ <Quantity(9.8, 'meter / second ** 2')>
+ >>> g.to('furlongs/fortnight**2')
+ <Quantity(7.12770743e+10, 'furlong / fortnight ** 2')>
+
+And behaves well when given dimensionless quantities, which are parsed into
+their appropriate objects:
+
+.. doctest::
+
+ >>> ureg('2.54')
+ 2.54
+ >>> type(ureg('2.54'))
+ <class 'float'>
+ >>> Q_('2.54')
+ <Quantity(2.54, 'dimensionless')>
+ >>> type(Q_('2.54'))
+ <class 'pint.quantity.build_quantity_class.<locals>.Quantity'>
+
+.. note:: Pint's rule for parsing strings with a mixture of numbers and
+ units is that **units are treated with the same precedence as numbers**.
+
+For example, the units of
+
+.. doctest::
+
+ >>> Q_('3 l / 100 km')
+ <Quantity(0.03, 'kilometer * liter')>
+
+may be unexpected at first but, are a consequence of applying this rule. Use
+brackets to get the expected result:
+
+.. doctest::
+
+ >>> Q_('3 l / (100 km)')
+ <Quantity(0.03, 'liter / kilometer')>
+
+.. note:: Since version 0.7, Pint **does not** use eval_ under the hood.
+ This change removes the `serious security problems`_ that the system is
+ exposed to when parsing information from untrusted sources.
+
+.. _eval: http://docs.python.org/3/library/functions.html#eval
+.. _`serious security problems`: http://nedbatchelder.com/blog/201206/eval_really_is_dangerous.html

docs/developers_reference.rst

@@ -2,8 +2,8 @@
 Developer reference
 ===================
 
-Pint
-====
+All Modules
+===========
 
 .. automodule:: pint
  :members:
@@ -55,60 +55,3 @@ Pint
 
 .. automodule:: pint.util
  :members:
-
-.. automodule:: pint.testsuite.helpers
- :members:
-
-.. automodule:: pint.testsuite.parameterized
- :members:
-
-.. automodule:: pint.testsuite.test_babel
- :members:
-
-.. automodule:: pint.testsuite.test_contexts
- :members:
-
-.. automodule:: pint.testsuite.test_converters
- :members:
-
-.. automodule:: pint.testsuite.test_definitions
- :members:
-
-.. automodule:: pint.testsuite.test_errors
- :members:
-
-.. automodule:: pint.testsuite.test_formatter
- :members:
-
-.. automodule:: pint.testsuite.test_infer_base_unit
- :members:
-
-.. automodule:: pint.testsuite.test_issues
- :members:
-
-.. automodule:: pint.testsuite.test_measurement
- :members:
-
-.. automodule:: pint.testsuite.test_numpy
- :members:
-
-.. automodule:: pint.testsuite.test_pint_eval
- :members:
-
-.. automodule:: pint.testsuite.test_pitheorem
- :members:
-
-.. automodule:: pint.testsuite.test_quantity
- :members:
-
-.. automodule:: pint.testsuite.test_systems
- :members:
-
-.. automodule:: pint.testsuite.test_umath
- :members:
-
-.. automodule:: pint.testsuite.test_unit
- :members:
-
-.. automodule:: pint.testsuite.test_util
- :members:

docs/getting.rst

@@ -9,32 +9,26 @@ You can install it (or upgrade to the latest version) using pip_::
 
  $ pip install -U pint
 
-That's all! You can check that Pint is correctly installed by starting up python, and importing pint:
+That's all! You can check that Pint is correctly installed by starting up python, and importing Pint:
 
 .. code-block:: python
 
  >>> import pint
  >>> pint.__version__ # doctest: +SKIP
 
+Or running the test suite:
+
+.. code-block:: python
+
+ >>> pint.test()
+
 .. note:: If you have an old system installation of Python and you don't want to
  mess with it, you can try `Anaconda CE`_. It is a free Python distribution by
  Continuum Analytics that includes many scientific packages. To install pint
  from the conda-forge channel instead of through pip use::
 
  $ conda install -c conda-forge pint
 
-You can check the installation with the following command:
-
-.. code-block:: python
-
- >>> pint.test() # doctest: +SKIP
-
-
-On Arch Linux, you can alternatively install Pint from the Arch User Repository
-(AUR). The latest release is available as `python-pint`_, and packages tracking
-the master branch of the GitHub repository are available as `python-pint-git`_
-and `python2-pint-git`_.
-
 
 Getting the code
 ----------------
@@ -56,13 +50,9 @@ Once you have a copy of the source, you can embed it in your Python package, or
  $ python setup.py install
 
 
-
 .. _easy_install: http://pypi.python.org/pypi/setuptools
 .. _Python: http://www.python.org/
 .. _pip: http://www.pip-installer.org/
 .. _`Anaconda CE`: https://store.continuum.io/cshop/anaconda
-.. _`python-pint`: https://aur.archlinux.org/packages/python-pint/
-.. _`python-pint-git`: https://aur.archlinux.org/packages/python-pint-git/
-.. _`python2-pint-git`: https://aur.archlinux.org/packages/python2-pint-git/
 .. _PyPI: https://pypi.python.org/pypi/Pint/
 .. _GitHub: https://github.com/hgrecco/pint

docs/index.rst

@@ -17,8 +17,7 @@ without changing the source code. It supports a lot of numpy mathematical
 operations **without monkey patching or wrapping numpy**.
 
 It has a complete test coverage. It runs in Python 3.6+ with no other
-dependency. It is licensed under BSD.
-
+dependencies. It is licensed under a `BSD 3-clause style license`_.
 
 It is extremely easy and natural to use:
 
@@ -39,6 +38,7 @@ and you can make good use of numpy if you want:
  >>> np.sum(_)
  <Quantity(7.07, 'meter')>
 
+See the :ref:`Tutorial` for more help getting started.
 
 Quick Installation
 ------------------
@@ -57,6 +57,8 @@ or utilizing conda, with the conda-forge channel:
 
 and then simply enjoy it!
 
+(See :ref:`Installation <getting>` for more detail.)
+
 
 Design principles
 -----------------
@@ -80,12 +82,12 @@ LaTeX and pretty formatting. Unit name translation is available if Babel_ is
 installed.
 
 **Free to choose the numerical type**: You can use any numerical type
-(`fraction`, `float`, `decimal`, `numpy.ndarray`, etc). NumPy_ is not required
-but supported.
+(``fraction``, ``float``, ``decimal``, ``numpy.ndarray``, etc). NumPy_ is not
+required, but is supported.
 
 **Awesome NumPy integration**: When you choose to use a NumPy_ ndarray, its methods and
 ufuncs are supported including automatic conversion of units. For example
-`numpy.arccos(q)` will require a dimensionless `q` and the units of the output
+``numpy.arccos(q)`` will require a dimensionless ``q`` and the units of the output
 quantity will be radian.
 
 **Uncertainties integration**: transparently handles calculations with
@@ -98,13 +100,15 @@ points, like positions on a map or absolute temperature scales.
 **Dependency free**: it depends only on Python and its standard library. It interacts with other packages
 like numpy and uncertainties if they are installed
 
-**Pandas integration**: Thanks to `Pandas Extension Types`_ it is now possible to use Pint with Pandas. Operations on DataFrames and between columns are units aware, providing even more convenience for users of Pandas DataFrames. For full details, see the `pint-pandas Jupyter notebook`_.
+**Pandas integration**: Thanks to `Pandas Extension Types`_ it is now possible to use Pint with Pandas.
+Operations on DataFrames and between columns are units aware, providing even more convenience for users
+of Pandas DataFrames. For full details, see the `pint-pandas Jupyter notebook`_.
 
 
 When you choose to use a NumPy_ ndarray, its methods and
 ufuncs are supported including automatic conversion of units. For example
-`numpy.arccos(q)` will require a dimensionless `q` and the units of the output
-quantity will be radian.
+``numpy.arccos(q)`` will require a dimensionless ``q`` and the units
+of the output quantity will be radian.
 
 
 User Guide
@@ -115,6 +119,7 @@ User Guide
 
  getting
  tutorial
+ defining-quantities
  numpy
  nonmult
  wrapping
@@ -160,3 +165,4 @@ One last thing
 .. _`Babel`: http://babel.pocoo.org/
 .. _`Pandas Extension Types`: https://pandas.pydata.org/pandas-docs/stable/extending.html#extension-types
 .. _`pint-pandas Jupyter notebook`: https://github.com/hgrecco/pint-pandas/blob/master/notebooks/pandas_support.ipynb
+.. _`BSD 3-clause style license`: https://github.com/hgrecco/pint/blob/master/LICENSE