add pluralize example

doc/examples.rst

@@ -978,3 +978,38 @@ When run, the script prints something like this::
    1 BTC = $17,211.91
       $1 = 5,810 sat
 
+.. pluralize example {{{1
+.. _quantiphy pluralize example:
+
+Pluralize
+---------
+
+Using some external packages you can monkey patch a new method into *Quantity* 
+that converts quantities into the singular or plural forms of speech.
+
+.. ignore:
+
+    >>> Quantity.set_prefs(spacer=' ')
+
+.. code-block:: python
+
+    >>> from quantiphy import Quantity
+    >>> from inform import plural
+
+    >>> def pluralize(self):
+    ...     with self.prefs(form='fixed', show_units=False):
+    ...         return plural(self).format(self.plural_format)
+
+    >>> class Loaves(Quantity):
+    ...     units = 'loaves'
+    ...     plural_format = "# /loaf/loaves"
+    ...     pluralize = pluralize
+
+    >>> with Quantity.prefs(form='fixed'):
+    ...     for count in [0, 1, 2, 0.5]:
+    ...         q = Loaves(count)
+    ...         print(q, '->', q.pluralize())
+    0 loaves -> 0 loaves
+    1 loaves -> 1 loaf
+    2 loaves -> 2 loaves
+    0.5 loaves -> 0.5 loaves

quantiphy/quantiphy.py

@@ -967,6 +967,10 @@ def set_prefs(cls, **kwargs):
 
         :type show_label: 'f', 'a', or bool
 
+        :arg bool show_units:
+            Whether the units should be included when rendering a quantity to a
+            string.  By default *show_units* is True.
+
         :arg str spacer:
             The spacer text to be inserted in a string between the numeric value
             and the scale factor when units are present.  Is generally specified

tests/test_doctests.py

@@ -35,7 +35,7 @@ def test_manual():
         '../doc/index.rst': 31,
         '../doc/user.rst': 450,
         '../doc/api.rst': 0,
-        '../doc/examples.rst': 36,
+        '../doc/examples.rst': 42,
         '../doc/accessories.rst': 12,
         '../doc/releases.rst': 0,
     }