Better __init__.py docs

implementations/python/preserves/__init__.py

@@ -1,27 +1,59 @@
-'''
-```
+'''```
 import preserves
 ```
 
 The main package re-exports a subset of the exports of its constituent modules:
 
-(TODO: improve the presentation of this list)
+- From [preserves.values][]:
+    - [Annotated][preserves.values.Annotated]
+    - [Embedded][preserves.values.Embedded]
+    - [Float][preserves.values.Float]
+    - [ImmutableDict][preserves.values.ImmutableDict]
+    - [Record][preserves.values.Record]
+    - [Symbol][preserves.values.Symbol]
+    - [annotate][preserves.values.annotate]
+    - [is_annotated][preserves.values.is_annotated]
+    - [preserve][preserves.values.preserve]
+    - [strip_annotations][preserves.values.strip_annotations]
 
-- From [`values`](/values): `Float, Symbol, Record, ImmutableDict, Embedded, preserve, Annotated, is_annotated, strip_annotations, annotate`
+- From [preserves.error][]:
+    - [DecodeError][preserves.error.DecodeError]
+    - [EncodeError][preserves.error.EncodeError]
+    - [ShortPacket][preserves.error.ShortPacket]
 
-- From [`compare`](/compare): `cmp`
+- From [preserves.binary][]:
+    - [Decoder][preserves.binary.Decoder]
+    - [Encoder][preserves.binary.Encoder]
+    - [canonicalize][preserves.binary.canonicalize]
+    - [decode][preserves.binary.decode]
+    - [decode_with_annotations][preserves.binary.decode_with_annotations]
+    - [encode][preserves.binary.encode]
 
-- From [`error`](/error): `DecodeError, EncodeError, ShortPacket`
+- From [preserves.text][]:
+    - [Formatter][preserves.text.Formatter]
+    - [Parser][preserves.text.Parser]
+    - [parse][preserves.text.parse]
+    - [parse_with_annotations][preserves.text.parse_with_annotations]
+    - [stringify][preserves.text.stringify]
 
-- From [`binary`](/binary): `Decoder, Encoder, decode, decode_with_annotations, encode, canonicalize`
+- From [preserves.compare][]:
+    - [cmp][preserves.compare.cmp]
 
-- From [`text`](/text): `Parser, Formatter, parse, parse_with_annotations, stringify`
+- From [preserves.merge][]:
+    - [merge][preserves.merge.merge]
 
-- From [`merge`](/merge): `merge`
+It also exports the [compare][preserves.compare] and [fold][preserves.fold] modules themselves,
+permitting patterns like
 
-- and submodules [`fold`](/fold) and [`compare`](/compare).
+```python
+>>> from preserves import *
+>>> compare.cmp(123, 234)
+-1
+
+```
+
+Finally, it provides a few utility aliases for common tasks:
 
-In addition, it provides a few utility aliases for common tasks:
 '''
 
 from .values import Float, Symbol, Record, ImmutableDict, Embedded, preserve