Restructure the documentation, removing redundancies.

Author: Ken Kundert

doc/api.rst renamed to doc/exceptions.rst

@@ -1,21 +1,5 @@
-Programmer's Interface
-======================
-
-
-Reader
-------
-
-.. autofunction:: nestedtext.loads
-
-
-Writer
-------
-
-.. autofunction:: nestedtext.dumps
-
-
-Exception
----------
+Exceptions
+----------
 
 *NestedText* imports the *Error* exception from `inform 
 <https://inform.readthedocs.io/en/stable/api.html#exceptions>`_ and renames it 
@@ -30,7 +14,9 @@ exception there.
 
 
 As with most exceptions, you can simply cast it to a string to get a reasonable 
-error message:
+error message.
+
+**Example:**
 
 .. code-block:: python
 
@@ -52,6 +38,8 @@ You can also use the *report* method to print the message directly. This is
 appropriate if you are using *inform* for your messaging as it follows 
 *inform*'s conventions.
 
+**Example:**
+
 .. code-block:: python
 
     >> try:
@@ -61,6 +49,8 @@ appropriate if you are using *inform* for your messaging as it follows
 
 The *terminate* method prints the message directly and exits.
 
+**Example:**
+
 .. code-block:: python
 
     >> try:
@@ -73,7 +63,9 @@ contains the basic text of the message. You can change this message by
 overriding the attribute when using *report*, *terminate*, or *render*.  
 *render* is like casting the exception to a string except that allows for the
 passing of arguments.  For example, to convert a particular message to Spanish, 
-you could use:
+you could use something like the following.
+
+**Example:**
 
 .. code-block:: python
 
@@ -85,4 +77,3 @@ you could use:
     ...         template = 'llave duplicada: {}.'
     ...     print(e.render(template=template))
     3: llave duplicada: name.
-

doc/index.rst

@@ -96,7 +96,7 @@ Documentation
    format
    reader
    writer
-   api
+   exceptions
    releases
 
 *  :ref:`genindex`

doc/reader.rst

@@ -1,8 +1,11 @@
 Reader
 ------
 
-You can read *NestedTest* data using :func:`nestedtext.loads()`, which takes 
-a string as an argument:
+*loads* converts *NestedText* to Python data objects.
+
+.. autofunction:: nestedtext.loads
+
+**Example:**
 
 .. code-block:: python
 
@@ -27,10 +30,24 @@ a string as an argument:
         'age': '74',
     }
 
+*NestedText* is specified to *loads* in the form of a string:
+
 *loads()* takes an optional second argument, *culprit*. If specified, it will be 
 prepended to any error messages. It is often used to designate the source of 
 *contents*. For example,if *contents* were read from a file, *culprit* would be 
-the file name.
+the file name.  Here is a typical example of reading *NestedText* from a file:
+
+**Example:**
+
+.. code-block:: python
+
+    >>> filename = 'examples/duplicate-keys.nt'
+    >>> try:
+    ...     with open(filename) as f:
+    ...         addresses = nestedtext.loads(f.read(), filename)
+    ... except nestedtext.NestedTextError as e:
+    ...     print(str(e))
+    examples/duplicate-keys.nt, 5: duplicate key: name.
 
 
 *NestedText* as a Structure Parser

doc/writer.rst

@@ -1,8 +1,11 @@
 Writer
 ------
 
-You can use :func:`nestedtext.dumps()` to convert a data structure consisting of 
-dictionaries, lists, and strings to *NestedText*:
+*dumps* converts Python data objects to *NextedText*.
+
+.. autofunction:: nestedtext.dumps
+
+**Example:**
 
 .. code-block:: python
 
@@ -37,7 +40,9 @@ list-like types such as *tuple* and *set* by converting them to the types
 supported by the format.  This implies that a round trip through *dumps* and 
 *loads* could result in the types of values being transformed. You can prevent 
 this by passing `default='strict'` to *dumps*.  Doing so means that values that 
-are not dictionaries, lists, or strings generate exceptions:
+are not dictionaries, lists, or strings generate exceptions.
+
+**Example:**
 
 .. code-block:: python
 
@@ -59,7 +64,9 @@ are not dictionaries, lists, or strings generate exceptions:
 
 Alternatively, you can specify a function to *default*, which is used to convert 
 values to strings.  It is used if no other converter is available.  Typical 
-values are *str* and *repr*:
+values are *str* and *repr*.
+
+**Example:**
 
 .. code-block:: python
 
@@ -85,7 +92,9 @@ values are *str* and *repr*:
     house: red
 
 You can also specify a dictionary of renderers. The dictionary maps the object 
-type to a render function:
+type to a render function.
+
+**Example:**
 
 .. code-block:: python
 
@@ -106,7 +115,9 @@ type to a render function:
     house: red
 
 If the dictionary maps a type to *None*, then the default behavior is used for 
-that type. If it maps to *False*, then an exception is raised:
+that type. If it maps to *False*, then an exception is raised.
+
+**Example:**
 
 .. code-block:: python
 

examples/address.nt

@@ -0,0 +1,39 @@
+# Contact information for our officers
+
+president:
+    name: Katheryn McDaniel
+    address:
+        > 138 Almond Street
+        > Topika, Kansas 20697
+    phone:
+        cell: 1-210-555-5297
+        home: 1-210-555-8470
+    email: [email protected]
+    kids:
+        - Joanie
+        - Terrance
+
+vice president:
+    name: Margaret Hodge
+    address:
+        > 2586 Marigold Lane
+        > Topika, Kansas 20682
+    phone: 1-470-555-0398
+    email: [email protected]
+    kids:
+        - Arnie
+        - Zach
+        - Maggie
+
+treasurer:
+    name: Fumiko Purvis
+    address:
+        > 3636 Buffalo Ave
+        > Topika, Kansas 20692
+    phone: 1-268-555-0280
+    email: [email protected]
+    kids:
+        - Lue
+    comments:
+        > Fumiko's term is ending at the end of the year.
+        > She will be replaced by Mariah Mobley.

examples/duplicate-keys.nt

@@ -0,0 +1,5 @@
+# this is an invalid NestedText file because it contains a dictionary with 
+# duplicate keys
+
+name:
+name:

nestedtext.py

@@ -294,22 +294,6 @@ def loads(contents, culprit=None):
     Returns:
         A dictionary or list containing the data.  If contents is empty, an
         empty dictionary is returned.
-
-    **Example**::
-
-        >>> import nestedtext
-        >>> contents = '''
-        ... name: Deryl McKinnon
-        ... phone: 212-590-3107
-        ... '''
-
-        try:
-            data = nestedtext.loads(contents)
-            print(data)
-        except nestedtext.NestedTextError as e:
-            e.report()
-        {'name': 'Deryl McKinnon', 'phone': 'phone: 212-590-3107'}
-
     """
     with set_culprit(culprit):
         lines = Lines(contents)
@@ -370,82 +354,6 @@ def dumps(obj, *, sort_keys=False, indent=4, renderers=None, default=None, level
             this is used to increment the level and so the indent.  Generally
             not specified by the user, but can be useful in unusual situations
             to specify an initial indent.
-
-    **Example**::
-
-        >>> import nestedtext
-
-        >>> try:
-        ...     print(nestedtext.dumps({'a': [0, 1], 'b': [2, 3, 4]}))
-        ... except nestedtext.NestedTextError as e:
-        ...     e.report()
-        a:
-            - 0
-            - 1
-        b:
-            - 2
-            - 3
-            - 4
-
-    *dumps* has built in support for the base Python types of *None*, *bool*,
-    *str*, *float*, *list*, *tuple*, *set*, and *dict*.  If *default* = 'strict'
-    is specified, that list shrinks to *str*, *list*, and *dict*.
-
-    You must make special arrangements to handle objects of other types.  There
-    are two approaches that can be used separately or together. You can specify
-    a default renderer that converts any unknown object type to a string.
-
-    **Example**::
-
-        >>> class Color:
-        ...     def __init__(self, color):
-        ...         self.color = color
-        ...     def __repr__(self):
-        ...         return f'Color({self.color!r})'
-        ...     def __str__(self):
-        ...         return self.color
-
-        >>> data = {'key': 42, 'value': 3.1415926, 'valid': True, 'color': Color('red')}
-        >>> try:
-        ...     print(nestedtext.dumps(data))
-        ... except nestedtext.NestedTextError as e:
-        ...     print(str(e))
-        Color('red'): unsupported type.
-
-        >>> print(nestedtext.dumps(data, default=repr))
-        key: 42
-        value: 3.1415926
-        valid: True
-        color: "Color('red')"
-
-        >>> print(nestedtext.dumps(data, default=str))
-        key: 42
-        value: 3.1415926
-        valid: True
-        color: red
-
-    You may also specify a dictionary of renderers.
-
-    **Example**::
-
-        >>> renderers = {
-        ...     bool: lambda b: 'yes' if b else 'no',
-        ...     int: hex,
-        ...     float: lambda f: f'{f:0.3}',
-        ...     Color: lambda c: c.color,
-        ... }
-
-        >>> try:
-        ...     print(nestedtext.dumps(data, renderers=renderers))
-        ... except nestedtext.NestedTextError as e:
-        ...     e.report()
-        key: 0x2a
-        value: 3.14
-        valid: yes
-        color: red
-
-    Mapping a type to *False* in *renderers* results in an exception being
-    raised if that type is found.
     """
 
     # define sort function