In Quantity.extract() remove constraint that names be identifiers.

Refine the documentation.

doc/.static/css/custom.css

@@ -0,0 +1,8 @@
+/*
+ * the following is used to make the highlighting that introduces classes, 
+ * methods, functions, etc extend across the width of the page.
+ */
+dt:first-child {
+    width: 100%;
+}
+

doc/api.rst

@@ -2,5 +2,23 @@
 Classes and Functions
 ---------------------
 
-.. automodule:: quantiphy
+
+Quantities
+==========
+
+.. autoclass:: quantiphy.Quantity
     :members:
+
+
+Unit Conversion
+===============
+
+.. autoclass:: quantiphy.UnitConversion
+
+
+Constants and Unit Systems
+==========================
+
+.. autofunction:: quantiphy.add_constant
+
+.. autofunction:: quantiphy.set_unit_system

doc/conf.py

@@ -217,7 +217,7 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'quantiphy', u'QuantiPhy Documentation',
-     [u'Ken Kundert'], 1)
+     [u'Ken Kundert'], 3)
 ]
 
 # If true, show URL addresses after external links.
@@ -231,7 +231,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'QuantiPhy', u'QuantiPhy Documentation',
-   u'Ken Kundert', 'QuantiPhy', 'One line description of project.',
+   u'Ken Kundert', 'QuantiPhy', 'Physical Quantities.',
    'Miscellaneous'),
 ]
 
@@ -244,6 +244,9 @@
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
 
-# Order used for autodoc members
-autodoc_member_order = 'bysource'
+#KSK: add custom css code if present
+def setup(app):
+    import os
+    if os.path.exists('css/custom.css'):
+        app.add_stylesheet('css/custom.css')
 

doc/examples.rst

@@ -406,7 +406,7 @@ produces an SVG version of the results using MatPlotLib.
     from matplotlib.ticker import FuncFormatter
     import matplotlib.pyplot as pl
     from quantiphy import Quantity
-    Quantity.set_prefs(map_sf=Quantity.map_sf_to_greek)
+    Quantity.set_prefs(map_sf=Quantity.map_sf_to_sci_notation)
 
     # read the data from delta-sigma.smpl
     data = np.fromfile('delta-sigma.smpl', sep=' ')
@@ -461,3 +461,19 @@ And the following is one of the two graphs produced:
 
 Notice the axis labels in the generated graph.  Use of *QuantiPhy* makes the 
 widely scaled units compact and easy to read.
+
+MatPlotLib provides the `EngFormatter 
+<https://matplotlib.org/examples/api/engineering_formatter.html>`_ that you can 
+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* 
+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 
+engineering scientific notation (ex: 13.806×10⁻²⁴ J/K) when no scale factors are 
+appropriate.  Though not necessary, that was done above with the line::
+
+    Quantity.set_prefs(map_sf=Quantity.map_sf_to_sci_notation)

doc/user.rst

@@ -220,16 +220,16 @@ conversion is under the control of the *assign_rec* preference.  The default
 version of *assign_rec* accepts either '=' or ':' to separate the name from the 
 value, and either '--', '#', or '//' to separate the value from the description 
 if a description is given. Thus, by default *QuantiPhy* recognizes 
-specifications of the following forms:
-
-    | <name> = <value>
-    | <name> = <value> -- <description>
-    | <name> = <value> # <description>
-    | <name> = <value> // <description>
-    | <name>: <value>
-    | <name>: <value> -- <description>
-    | <name>: <value> # <description>
-    | <name>: <value> // <description>
+specifications of the following forms::
+
+    <name> = <value>
+    <name> = <value> -- <description>
+    <name> = <value> # <description>
+    <name> = <value> // <description>
+    <name>: <value>
+    <name>: <value> -- <description>
+    <name>: <value> # <description>
+    <name>: <value> // <description>
 
 For example: