add doc on diffs

9 files changed, 40 insertions, 20 deletions

diff --git a/ansicolor/ansicolor.py b/ansicolor/ansicolor.py
index 48af015..c79902a 100644
--- a/ansicolor/ansicolor.py
+++ b/ansicolor/ansicolor.py
@@ -368,7 +368,8 @@ def colordiff(x, y, color_x=Colors.Cyan, color_y=Colors.Green, debug=False):
 
 def justify_formatted(s, justify_func, width):
     """
-    Justify a formatted string to a width using a function (eg. ``string.ljust``).
+    Justify a formatted string to a width using a function
+    (eg. ``string.ljust``).
 
     :param string s: The formatted string.
     :param justify_func: The justify function.
diff --git a/docs/index.rst b/docs/index.rst
index 640b673..f72e854 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,10 +1,5 @@
-.. ansicolor documentation master file, created by
-   sphinx-quickstart on Sat Mar  8 22:11:18 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to ansicolor's documentation!
-=====================================
+ansicolor
+=========
 
 User guide
 ----------
@@ -13,8 +8,10 @@ User guide
    :maxdepth: 4
 
    src/getting_started.rst
+   src/using_highlights.rst
+   src/colored_diffs.rst
 
-API Documentation
+API documentation
 -----------------
 
 .. toctree::
diff --git a/docs/snippets/colored_diffs_1.png b/docs/snippets/colored_diffs_1.png
new file mode 100644
index 0000000..800af69
--- /dev/null
+++ b/docs/snippets/colored_diffs_1.png
diff --git a/docs/snippets/colored_diffs_1.py b/docs/snippets/colored_diffs_1.py
new file mode 100644
index 0000000..6274aa1
--- /dev/null
+++ b/docs/snippets/colored_diffs_1.py
@@ -0,0 +1,11 @@
+from ansicolor import Colors
+from ansicolor import colordiff
+
+statement = "All towles must be folded an stowed away neatly inthe closet."
+reviewed = "All towels must be folded and stowed neatly in the closet!"
+
+first, second = colordiff(statement, reviewed,
+                          color_x=Colors.Cyan, color_y=Colors.Green)
+
+print(first)
+print(second)
diff --git a/docs/snippets/getting_started_2.py b/docs/snippets/getting_started_2.py
new file mode 100644
index 0000000..8689926
--- /dev/null
+++ b/docs/snippets/getting_started_2.py
@@ -0,0 +1,4 @@
+from ansicolor import Colors
+from ansicolor import colorize
+
+print(colorize("I'm blue", Colors.Blue))
diff --git a/docs/snippets/getting_started_3.png b/docs/snippets/getting_started_3.png
new file mode 100644
index 0000000..275dc66
--- /dev/null
+++ b/docs/snippets/getting_started_3.png
diff --git a/docs/snippets/getting_started_3.py b/docs/snippets/getting_started_3.py
new file mode 100644
index 0000000..c7d3b62
--- /dev/null
+++ b/docs/snippets/getting_started_3.py
@@ -0,0 +1,4 @@
+from ansicolor import Colors
+from ansicolor import wrap_string
+
+print(wrap_string("I'm blue, said the smurf.", 8, Colors.Blue))
diff --git a/docs/src/colored_diffs.rst b/docs/src/colored_diffs.rst
new file mode 100644
index 0000000..0bb702e
--- /dev/null
+++ b/docs/src/colored_diffs.rst
@@ -0,0 +1,11 @@
+Colored diffs
+=============
+
+One practical use of colors is to make differences in text more visible.
+:data:`ansicolor.colordiff` computes a diff of two strings and returns
+a marked-up version of them that highlights the characters that differ
+between the two.
+
+.. literalinclude:: ../snippets/colored_diffs_1.py
+
+.. figure:: ../snippets/colored_diffs_1.png
diff --git a/docs/src/getting_started.rst b/docs/src/getting_started.rst
index 28ad000..c5a724f 100644
--- a/docs/src/getting_started.rst
+++ b/docs/src/getting_started.rst
@@ -22,22 +22,14 @@ to reset the color back to the default:
 If I want to be able to pass a color as an argument I can also use the
 ``colorize`` function:
 
-.. code:: python
-
-    from ansicolor import Colors
-    from ansicolor import colorize
-
-    print(colorize("I'm blue", Colors.Blue))
+.. literalinclude:: ../snippets/getting_started_2.py
 
 
 I can also apply color on a portion of a string:
 
-.. code:: python
-
-    from ansicolor import Colors
-    from ansicolor import wrap_string
+.. literalinclude:: ../snippets/getting_started_3.py
 
-    print(wrap_string("I'm blue, said the policeman.", 8, Colors.Blue))
+.. figure:: ../snippets/getting_started_3.png
 
 
 Sometimes I may have a string that contains markup and I'll want to do something