From 54774dd513a53268f3606a9e00819d715735ce54 Mon Sep 17 00:00:00 2001 From: Ken Kundert Date: Mon, 7 Aug 2017 20:12:57 -0700 Subject: [PATCH] Refine the documentation. --- doc/examples.rst | 28 +++++++++++++++------------- doc/releases.rst | 4 ++++ quantiphy.py | 11 +++++++---- 3 files changed, 26 insertions(+), 17 deletions(-) diff --git a/doc/examples.rst b/doc/examples.rst index fcd384a..1be0ff3 100644 --- a/doc/examples.rst +++ b/doc/examples.rst @@ -14,10 +14,12 @@ units into physical quantities. Physical quantities are very commonly encountered when working with real-world systems when numbers are involved. And when encountered, the numbers often use SI scale factors to make them easier to read and write. Surprisingly, most computer languages do not support numbers in -these forms, meaning that when working with physical quantities, one often has -to choose between using a form that is easy for computers to read or one that is -easy for humans to read. For example, consider this table of critical -frequencies needed in jitter tolerance measurements in optical communication: +these forms. + +When working with physical quantities, one often has to choose between using +a form that is easy for computers to read or one that is easy for humans to +read. For example, consider this table of critical frequencies needed in jitter +tolerance measurements in optical communication: .. code-block:: python @@ -222,13 +224,13 @@ demonstrate several of the features of *QuantiPhy*. Vt = 25.852 mV # thermal voltage The first part of this example imports :class:`quantiphy.Quantity` and sets the -*show_label* and *label_fmt* preferences to display both the value and the -description by default. *label_fmt* is given as a tuple of two strings, the -first will be used when the description is present, the second is used when it -is not. In the first string, the ``{V:<16}`` is replaced by the expansion of the -second string, left justified with a field width of 16, and the ``{d}`` is -replaced by the description. On the second string the ``{n}`` is replaced by the -*name* and ``{v}`` is replaced by the value (numeric value and units). +*show_label*, *label_fmt* and *label_fmt_full* preferences to display both the +value and the description by default. *label_fmt* is used when the description +is not present and *label_fmt_full* is used when it is present. In *label_fmt* +the ``{n}`` is replaced by the *name* and ``{v}`` is replaced by the value +(numeric value and units). In *label_fmt_full*, the ``{V:<18}`` is replaced by +the expansion of *label_fmt*, left justified with a field width of 18, and the +``{d}`` is replaced by the description. The second part defines four quantities. The first is given in a very specific way to avoid the ambiguity between units and scale factors. In this case, the @@ -518,8 +520,8 @@ use as an alternative to *QuantiPhy* for formatting your axes with SI scale factors, which also provides the *format_eng* function for converting floats to strings formatted with SI scale factors and units. So if your needs are limited, as they are in this example, that is generally a good way to go. One aspect of -*QuantiPhi* that you might prefer is they way it handles very large or very -small numbers. As the numbers get either very large or very small *EngFormatter* +*QuantiPhi* that you might prefer is the way it handles very large or very small +numbers. As the numbers get either very large or very small *EngFormatter* starts by using unfamiliar scale factors (*YZPEzy*) and then reverts to e-notation. *QuantiPhy* allows you to control whether to use unfamiliar scale factors but does not use them by default. It also can be configured to revert to diff --git a/doc/releases.rst b/doc/releases.rst index 732d21d..91f2572 100644 --- a/doc/releases.rst +++ b/doc/releases.rst @@ -52,3 +52,7 @@ Releases - added support for SI standard composite units - added support for non-breaking space as spacer - removed constraint in extract() that names must be identifiers + +**Latest development release**: + | Version: 2.1.0 + | Released: 2017-07-30 diff --git a/quantiphy.py b/quantiphy.py index 16a3e7c..84f86f2 100644 --- a/quantiphy.py +++ b/quantiphy.py @@ -1564,12 +1564,15 @@ def extract(cls, text): The brackets indicate that the name/value pair and the description is optional. However, must be given if is given. - : the name is used as a key for the value. + : + the name is used as a key for the value. - : A number with optional units (ex: 3 or 1pF or 1 kOhm), - the units need not be a simple identifier (ex: 9.07 GHz/V). + : + A number with optional units (ex: 3 or 1pF or 1 kOhm), + the units need not be a simple identifier (ex: 9.07 GHz/V). - : Optional textual description (ex: Gain of PD (Imax)). + : + Optional textual description (ex: Frequency of hydrogen line). Blank lines and any line that does not contain a value are ignored. So with the default *assign_rec*, lines with the following form are