tweak examples, update readme

Author: samuelcolvin

README.rst

@@ -5,6 +5,10 @@ python devtools
 
 Dev tools for python.
 
+The debug print command python never had (and other things).
+
+For more information, see `documentation <https://python-devtools.helpmanual.io/>`_
+
 Install
 -------
 

docs/examples/prettier.py

@@ -1,9 +1,14 @@
 from devtools import PrettyFormat, pprint, pformat
+import numpy as np
 
 v = {
     'foo': {'whatever': [3, 2, 1]},
     'sentence': 'hello\nworld',
     'generator': (i * 2 for i in [1, 2, 3]),
+    'matrix': np.matrix([[1, 2, 3, 4],
+                         [50, 60, 70, 80],
+                         [900, 1000, 1100, 1200],
+                         [13000, 14000, 15000, 16000]])
 }
 
 # pretty print of v
@@ -15,7 +20,7 @@
 
 pp = PrettyFormat(
      indent_step=2,  # default: 4
-     indent_char='_',  # default: space
+     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

docs/index.rst

@@ -23,8 +23,8 @@ 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
------------
+Debug
+-----
 
 Somehow in the 26 years (and counting) of active development of python, no one thought to add a simple
 and readable way to print stuff during development. (If you know why this is, I'd love to hear).
@@ -45,13 +45,10 @@ you found down the back of a chair on the tube:
 
 * each output is prefixed with the file, line number and function where ``debug`` was called
 * the variable name or expression being printed is shown
-* each argument is printed "pretty" on a new line
+* each argument is printed "pretty" on a new line, see :ref:`prettier print <prettier_print>`
 * if ``pygments`` is installed the output is highlighted
 
-Complex usage
-.............
-
-a more complex example of ``debug`` shows more of what it can do.
+A more complex example of ``debug`` shows more of what it can do.
 
 .. literalinclude:: examples/example2.py
 
@@ -62,34 +59,14 @@ a more complex example of ``debug`` shows more of what it can do.
 .. raw:: html
    :file: ./examples/example2.html
 
-Usage without import
-....................
-
-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 debug tools
 .................
 
 The debug namespace includes a number of other useful functions:
 
-* ``format()`` same as calling ``debug()`` but returns a ``DebugOutput`` rather than printing the output
-* ``timer()`` returns an instance of *devtool's* ``Timer`` class suitable for timing code execution
-* ``breakpoint()`` introduces a breakpoint using ``pdb``
+* ``debug.format()`` same as calling ``debug()`` but returns a ``DebugOutput`` rather than printing the output
+* ``debug.timer()`` returns an instance of *devtool's* ``Timer`` class suitable for timing code execution
+* ``debug.breakpoint()`` introduces a breakpoint using ``pdb``
 
 
 .. literalinclude:: examples/more_debug.py
@@ -101,11 +78,10 @@ The debug namespace includes a number of other useful functions:
 .. raw:: html
    :file: ./examples/more_debug.html
 
-Other Tools
------------
+.. _prettier_print:
 
 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
@@ -127,13 +103,33 @@ 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>`_.
 
+Usage without import
+--------------------
+
+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.
+
 .. include:: ../HISTORY.rst
 
 .. |pypi| image:: https://img.shields.io/pypi/v/devtools.svg