more examples; cosmetics

Author: mr-mixas

HOWTO.md

@@ -1,9 +1,93 @@
 # Nested-Diff.py HowTo
 
+## How to get shortest possible patch
+
+```py
+>>> from nested_diff import diff
+>>>
+>>> a = {'one': 1, 'two': 2, 'three': 'threeeeeeeee'}
+>>> b = {'one': 1, 'two': 42}
+>>>
+>>> diff(a, b, O=False, U=False, trimR=True)
+{'D': {'three': {'R': None}, 'two': {'N': 42}}}
+>>>
+```
+
+## How to get unchanged items only
+
+Diff calculates following changes by default:
+
+* A: added items.
+* N: new values for changed items.
+* O: old values for changed items.
+* R: removed items.
+* U: unchanged items.
+
+Thus disabling all except `U` diff will contain unchanged items only:
+
+```py
+>>> from nested_diff import Differ
+>>>
+>>> a = ['one', 'two', 'three']
+>>> b = ['ONE', 'two']
+>>>
+>>> differ = Differ(A=False, N=False, O=False, R=False, U=True)
+>>>
+>>> is_equal, diff = differ.diff(a, b)
+>>> is_equal
+False
+>>> diff
+{'D': [{'U': 'two', 'I': 1}]}
+>>>
+```
+
+## How to enable unified diffs for text values
+
+```py
+>>> from nested_diff import diff, handlers
+>>> from nested_diff.formatters import TextFormatter
+>>>
+>>> a = 'one\ntwo\nthree'
+>>> b = 'one\nthree'
+>>>
+>>> d =  diff(a, b, U=False, extra_handlers=[handlers.TextHandler(context=3)])
+>>> d
+{'D': [{'I': [0, 3, 0, 2]}, {'U': 'one'}, {'R': 'two'}, {'U': 'three'}], 'E': 5}
+>>>
+>>> print(TextFormatter().format(d))
+# <str>
+  @@ -1,3 +1,2 @@
+  one
+- two
+  three
+<BLANKLINE>
+>>>
+```
+
+## How to render diff to HTML
+
+```py
+>>> from nested_diff import diff
+>>> from nested_diff.formatters import HtmlFormatter
+>>>
+>>> a = ['a', 'b', 'c']
+>>> b = ['A', 'b']
+>>>
+>>> formatter = HtmlFormatter()
+>>> diff_ = diff(a, b)
+>>>
+>>> html_header = formatter.get_page_header(lang='en', title='Nested diff')
+>>> html_body = formatter.format(diff_)
+>>> html_footer = formatter.get_page_footer()
+>>>
+```
+
 ## How to diff objects with types unsupported by nested\_diff
 
-Custom type handlers may be set to support any desired types, have a look at
-`Differ.set_handler` method and [handlers.py](nested_diff/handlers.py).
+External handlers may be set to support any desired types.  
+Have a look at `Differ.set_handler` method for details and builtin set of
+[nested\_diff.handlers](https://github.com/mr-mixas/Nested-Diff.py/tree/master/nested_diff/handlers.py)
+for examples.
 
 ## How to ignore some differences during diff
 
@@ -38,6 +122,19 @@ assert differ.diff(a, b) == (False, {'D': [{'I': 2, 'N': 0.2, 'O': 0.1}]})
 >>>
 ```
 
+## How to treat NaNs as equals
+
+```py
+>>> from nested_diff import Differ, handlers
+>>>
+>>> differ = Differ()
+>>> differ.set_handler(handlers.FloatHandler(nans_equal=True))
+>>>
+>>> differ.diff(float('nan'), float('nan'))
+(True, {'U': nan})
+>>>
+```
+
 ## How to use nested\_diff tool with git
 
 Ensure `nested_diff` command available, otherwise install it with `pip`:

README.md

@@ -2,17 +2,18 @@
 
 Recursive diff and patch for nested structures.
 
-[![Tests Status](https://github.com/mr-mixas/Nested-Diff.py/actions/workflows/tests.yml/badge.svg)](https://github.com/mr-mixas/Nested-Diff.py/actions?query=branch%3Amaster)
-[![Coverage Status](https://coveralls.io/repos/github/mr-mixas/Nested-Diff.py/badge.svg)](https://coveralls.io/github/mr-mixas/Nested-Diff.py)
+[![PyPi](https://img.shields.io/pypi/v/nested-diff.svg)](https://pypi.python.org/pypi/nested-diff)
+[![Tests](https://github.com/mr-mixas/Nested-Diff.py/actions/workflows/tests.yml/badge.svg)](https://github.com/mr-mixas/Nested-Diff.py/actions?query=branch%3Amaster)
+[![Coverage](https://coveralls.io/repos/github/mr-mixas/Nested-Diff.py/badge.svg)](https://coveralls.io/github/mr-mixas/Nested-Diff.py)
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/nested_diff.svg)](https://pypi.org/project/nested_diff/)
 [![License](https://img.shields.io/pypi/l/nested_diff.svg)](https://pypi.org/project/nested_diff/)
 
 ## Main features
 
-* Machine-readable diff structure.
-* Human-friendly diff visualization, collapsible html diffs.
-* All operation tags are optional and may be disabled.
-* Extensibility.
+* Machine readable diff structure.
+* Human friendly diff visualization, collapsible html diffs.
+* All ops (added/removed/changed/unchanged) are optional and may be disabled.
+* Any data types support may be added by external handlers.
 
 **[See Live Demo!](https://nesteddiff.pythonanywhere.com/)**
 
@@ -48,52 +49,42 @@ nested_patch a.json patch.json
 
 ```py
 >>> from nested_diff import diff, patch
+>>> from nested_diff.formatters import TextFormatter
 >>>
 >>> a = {'one': 1, 'two': 2, 'three': 3}
 >>> b = {'one': 1, 'two': 42}
 >>>
->>> diff(a, b)
+>>>
+>>> full_diff = diff(a, b)
+>>> full_diff
 {'D': {'three': {'R': 3}, 'two': {'N': 42, 'O': 2}, 'one': {'U': 1}}}
 >>>
->>> diff(a, b, O=False, U=False)
+>>> short_diff = diff(a, b, O=False, U=False)  # omit old and unchanged items
+>>> short_diff
 {'D': {'three': {'R': 3}, 'two': {'N': 42}}}
 >>>
 >>>
->>> c = [0,1,2,3]
->>> d = [  1,2,4,5]
->>>
->>> c = patch(c, diff(c, d))
->>> assert c == d
->>>
-```
-
-### Formatting diffs
-
-```py
->>> from nested_diff import diff, handlers
->>> from nested_diff.formatters import TextFormatter
+>>> a = patch(a, short_diff)
+>>> assert a == b
 >>>
->>> a = {'one': 1, 'two': 'some\ntext\ninside'}
->>> b = {'one': 0, 'two': 'some\ntext'}
 >>>
->>> d = diff(a, b, U=False, extra_handlers=[handlers.TextHandler(context=3)])
->>> print(TextFormatter().format(d))
+>>> human_readable = TextFormatter().format(full_diff)
+>>> print(human_readable)
   {'one'}
--   1
-+   0
+    1
+- {'three'}
+-   3
   {'two'}
-#   <str>
-    @@ -1,3 +1,2 @@
-    some
-    text
--   inside
+-   2
++   42
 <BLANKLINE>
 >>>
 ```
 
-For more examples see [Live Demo](https://nesteddiff.pythonanywhere.com/),
+HTML and ANSI colored terminal formatters also available out of the box.  
+See [Live Demo](https://nesteddiff.pythonanywhere.com/),
 [HOWTO](https://github.com/mr-mixas/Nested-Diff.py/blob/master/HOWTO.md) and
-[tests](https://github.com/mr-mixas/Nested-Diff.py/tree/master/tests).
+[nested\_diff.formatters](https://github.com/mr-mixas/Nested-Diff.py/tree/master/nested_diff/formatters.py).
 
 ## Diff structure