adding more docs

Author: samuelcolvin

devtools/ansi.py

@@ -130,7 +130,7 @@ def __str__(self):
 
 class StylePrint:
     """
-    Annoyingly enums do not allow inheritance, this is a lazy design mistake, this is an ugly work around
+    Annoyingly enums do not allow inheritance, a lazy design mistake, this is an ugly work around
     for that mistake.
     """
     def __call__(self, input, *styles, reset=True, flush=True, file=None, **print_kwargs):

docs/examples/2_output.png

@@ -0,0 +1,10 @@
+from devtools import sprint, sformat
+
+sprint('this is red', sprint.red)
+
+sprint('this is bold underlined blue on a green background. yuck',
+       sprint.blue, sprint.bg_yellow, sprint.bold, sprint.underline)
+
+v = sformat('i am dim', sprint.dim)
+print(repr(v))
+# > '\x1b[2mi am dim\x1b[0m'

docs/examples/ansi_colours.py

@@ -0,0 +1,55 @@
+from devtools import PrettyFormat, pprint, pformat
+
+v = {
+    'foo': {'whatever': [3, 2, 1]},
+    'sentence': 'hello\nworld',
+    'generator': (i * 2 for i in [1, 2, 3]),
+}
+
+pprint(v)
+# > with colours:
+"""
+{
+    'foo': {
+        'whatever': [3, 2, 1],
+    },
+    'sentence': (
+        'hello\n'
+        'world'
+    ),
+    'generator': (
+        2,
+        4,
+        6,
+    ),
+}
+"""
+
+s = pformat(v, highlight=False)
+print(s)
+# > as above without colours, the generator will also be empty as it's already been evaluated
+
+pp = PrettyFormat(
+     indent_step=2,  # default: 4
+     indent_char='_',  # default: space
+     repr_strings=True,  # default: False
+     simple_cutoff=2,  # default: 10 (if repr is below this length it'll be shown on one line)
+     width=80,  # default: 120
+     yield_from_generators=False  # default: True (whether to evaluate generators)
+)
+
+print(pp(v))
+# >
+"""
+{
+__'foo': {
+____'whatever': [
+______'apple',
+______123,
+______45.67,
+____],
+__},
+__'sentence': 'hello\nworld',
+__'generator': <generator object <genexpr> at 0x7f448b7cebf8>,
+}
+"""

docs/examples/prettier.py

@@ -0,0 +1,8 @@
+...
+
+try:
+    from devtools import debug
+except ImportError:
+    pass
+else:
+    __builtins__['debug'] = debug

docs/examples/sitecustomize.py

@@ -21,7 +21,9 @@ If ``pygments`` is installed *devtools* will colourise output to make it even mo
 chances are you already have pygments installed if you're using ipython, otherwise it can be installed along
 with *devtools* via ``pip install devtools[pygments]``.
 
-debug print
+*python-devtools* has no requirements beyond python and optionally pygments.
+
+Debug print
 -----------
 
 Example:
@@ -40,6 +42,9 @@ you found down the back of a chair on the tube:
 * each argument is printed "pretty" on a new line with
 * if ``pygments`` is installed the output will be highlighted
 
+Complex usage
+.............
+
 a more complex example of ``debug`` shows more of what it can do.
 
 .. literalinclude:: examples/2_input.py
@@ -49,9 +54,53 @@ Will output:
 .. image:: examples/2_output.png
 
 
+Usage without import
+....................
 
-.. include:: ../HISTORY.rst
+We all know the annoyance of running code only to discover a missing import, this can be particularly
+frustrating when the function you're using isn't used except during development.
+
+You can setup your environment to make ``debug`` available at all times by editing ``sitecustomize.py``,
+with ubuntu and python3.6 this file can be found at ``/usr/lib/python3.6/sitecustomize.py`` but you might
+need to look elsewhere depending on your OS/python version.
+
+Add the following to ``sitecustomize.py``
+
+.. literalinclude:: examples/sitecustomize.py
+
+The ``ImportError`` exception is important since you'll want python to run fine even if *devtools* isn't installed.
+
+This approach has another advantage: if you forget to remove ``debug(...)`` calls from your code, CI
+(which won't have devtools installed) should fail both on execution and linting, meaning you don't end up with
+extraneous debug calls in production code.
+
+Other Tools
+-----------
 
+Prettier print
+..............
+
+Python comes with `pretty print <https://docs.python.org/3/library/pprint.html>`_, problem is quite often
+it's not that pretty, it also doesn't cope well with non standard python objects (think numpy arrays or
+django querysets) which have their own pretty print functionality.
+
+To get round this *devtools* comes with prettier print, my take on pretty printing. You can see it in use above
+in ``debug()``, but you can also call it directly:
+
+.. literalinclude:: examples/prettier.py
+
+For more details on prettier printing, see
+`prettier.py <https://github.com/samuelcolvin/python-devtools/blob/master/devtools/prettier.py>`_.
+
+ANSI terminal colours
+.....................
+
+.. literalinclude:: examples/ansi_colours.py
+
+For more details on ansi colours, see
+`ansi.py <https://github.com/samuelcolvin/python-devtools/blob/master/devtools/ansi.py>`_.
+
+.. include:: ../HISTORY.rst
 
 .. |pypi| image:: https://img.shields.io/pypi/v/python-devtools.svg
    :target: https://pypi.python.org/pypi/python-devtools