doc how to customize text repr; close pepkit#47

.gitignore

@@ -72,4 +72,4 @@ Thumbs.db
 build/
 dist/
 attmap.egg-info/
-
+docs/autodoc_build

docs/howto.md

@@ -0,0 +1,27 @@
+# Use cases and "how-to..."
+
+## ...customize a subtype's text rendition
+In a subclass, override `_excl_from_repr`, using key and/or type of value. 
+
+The most basic implementation is a no-op, excluding nothing:
+```python
+def _excl_from_repr(self, k, cls):
+    return False
+```
+
+To exclude by key, though, you can do something like:
+```python
+def _excl_from_repr(self, k, cls):
+    protected = ["reserved_metadata", "REZKEY"]
+    return k in protected
+```
+
+To exclude by value type, you can use something like:
+```python
+def _excl_from_repr(self, k, cls):
+    return issubclass(cls, BaseOmissionType)
+```
+where `BaseOmissionType` is a proxy for the name of some type of values that may 
+be stored in your mapping but that you prefer to not display in its text representation.
+
+The two kinds of exclusion criteria may be combined as desired.

mkdocs.yml

@@ -8,6 +8,7 @@ nav:
     - Home: README.md
   - Reference:
     - API: autodoc_build/attmap.md
+    - Howto: howto.md
     - Support: support.md
     - Contributing: contributing.md
     - Changelog: changelog.md