add doc on highlights

8 files changed, 105 insertions, 18 deletions

diff --git a/ansicolor/ansicolor.py b/ansicolor/ansicolor.py
index c79902a..9afbcc7 100644
--- a/ansicolor/ansicolor.py
+++ b/ansicolor/ansicolor.py
@@ -143,7 +143,7 @@ def get_code(color, bold=False, reverse=False):
 
 def colorize(s, color, bold=False, reverse=False):
     """
-    Colorize string with the color given.
+    Colorize a string with the color given.
 
     :param string s: The string to colorize.
     :param color: The color to use.
@@ -179,6 +179,7 @@ def wrap_string(s, pos, color, bold=False, reverse=False):
                          get_code(None),
                          s[pos:])
 
+
 def highlight_string(s, *spanlists, **kw):
     """
     Highlight spans in a string using a list of (begin, end) pairs. Each
@@ -187,7 +188,7 @@ def highlight_string(s, *spanlists, **kw):
 
     :param string s: The string to highlight
     :param list spanlists: A list of tuples on the form ``[(begin, end)*]*``
-    :param kw: can set bold, reverse, color or nocolor
+    :param kw: May include: `bold`, `reverse`, `color` and `nocolor`
     :rtype: string
     """
 
diff --git a/docs/index.rst b/docs/index.rst
index f72e854..5e3720d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,6 +10,7 @@ User guide
    src/getting_started.rst
    src/using_highlights.rst
    src/colored_diffs.rst
+   src/marked_up_strings.rst
 
 API documentation
 -----------------
diff --git a/docs/snippets/marked_up_strings_1.py b/docs/snippets/marked_up_strings_1.py
new file mode 100644
index 0000000..ced33ec
--- /dev/null
+++ b/docs/snippets/marked_up_strings_1.py
@@ -0,0 +1,4 @@
+from ansicolor import red
+from ansicolor import write_out
+
+write_out(red("This looks red in a terminal.\n"))
diff --git a/docs/snippets/using_highlights_1.png b/docs/snippets/using_highlights_1.png
new file mode 100644
index 0000000..0426824
--- /dev/null
+++ b/docs/snippets/using_highlights_1.png
diff --git a/docs/snippets/using_highlights_1.py b/docs/snippets/using_highlights_1.py
new file mode 100644
index 0000000..4c354b9
--- /dev/null
+++ b/docs/snippets/using_highlights_1.py
@@ -0,0 +1,41 @@
+import re
+
+from ansicolor import highlight_string
+
+text = """
+"What giants?" asked Sancho Panza.
+"The ones you can see over there," answered his master, "with the huge arms, some of which are very nearly two leagues long."
+"Now look, your grace," said Sancho, "what you see over there aren't giants, but windmills, and what seems to be arms are just their sails, that go around in the wind and turn the millstone."
+"Obviously," replied Don Quijote, "you don't know much about adventures."
+""".strip()
+
+def get_line_indices(text):
+    odds, evens = [], []
+    for i, match in enumerate(re.finditer('(?m)^.*$', text)):
+        start = match.start()
+        end = match.end()
+        if (i + 1) % 2 == 1:
+            odds.append((start, end))
+        else:
+            evens.append((start, end))
+    return odds, evens
+
+def get_word_indices(regex, text):
+    pairs = []
+    for i, match in enumerate(re.finditer(regex, text)):
+        start = match.start()
+        end = match.end()
+        pairs.append((start, end))
+    return pairs
+
+odds, evens = get_line_indices(text)
+characters = get_word_indices('(?i)(don quijote|master|sancho panza|sancho)', text)
+
+print(">> highlight only odds:")
+print(highlight_string(text, odds))
+
+print("\n>> highlight both:")
+print(highlight_string(text, odds, evens))
+
+print("\n>> highlight both + characters:")
+print(highlight_string(text, odds, evens, characters))
diff --git a/docs/src/getting_started.rst b/docs/src/getting_started.rst
index 58cb58e..4696015 100644
--- a/docs/src/getting_started.rst
+++ b/docs/src/getting_started.rst
@@ -32,19 +32,3 @@ I can also apply color on a portion of a string:
 .. literalinclude:: ../snippets/getting_started_3.py
 
 .. figure:: ../snippets/getting_started_3.png
-
-
-Sometimes I may have a string that contains markup and I'll want to do something
-with it that concerns only the text, so I can strip the markup:
-
-.. code:: python
-
-    >>> from ansicolor import red
-    >>> from ansicolor import strip_escapes
-    >>> from ansicolor import yellow
-
-    >>> message = "My favorite colors are %s and %s" % (yellow("yellow"), red("red"))
-    >>> print("The length of this text is not: %d" % len(message))
-    The length of this text is not: 67
-    >>> print("The length of this text is: %d" % len(strip_escapes(message)))
-    The length of this text is: 37
diff --git a/docs/src/marked_up_strings.rst b/docs/src/marked_up_strings.rst
new file mode 100644
index 0000000..dc36521
--- /dev/null
+++ b/docs/src/marked_up_strings.rst
@@ -0,0 +1,33 @@
+Working with marked-up strings
+==============================
+
+
+Stripping markup
+----------------
+
+Sometimes I may have a string that contains markup and I'll want to do something
+with it that concerns only the text, so I can strip the markup:
+
+.. code:: python
+
+    >>> from ansicolor import red
+    >>> from ansicolor import strip_escapes
+    >>> from ansicolor import yellow
+
+    >>> message = "My favorite colors are %s and %s" % (yellow("yellow"), red("red"))
+    >>> print("The length of this text is not: %d" % len(message))
+    The length of this text is not: 67
+    >>> print("The length of this text is: %d" % len(strip_escapes(message)))
+    The length of this text is: 37
+
+
+Producing output
+----------------
+
+Printing marked-up strings directly is not appropriate for all use cases. When
+writing to a file it's generally not desirable to print ansi escapes meant
+for a terminal. The two functions :data:`ansicolor.write_out` and
+:data:`ansicolor.write_err` omit ansi escapes if the file being written to is
+not a tty.
+
+.. literalinclude:: ../snippets/marked_up_strings_1.py
diff --git a/docs/src/using_highlights.rst b/docs/src/using_highlights.rst
new file mode 100644
index 0000000..0fbd4bb
--- /dev/null
+++ b/docs/src/using_highlights.rst
@@ -0,0 +1,23 @@
+Using highlights
+================
+
+Quite often colors are used not to format all of the text in color, but to
+highlight certain parts of it.
+The function :data:`ansicolor.highlight_string` takes this a
+bit further by allowing you to pass in a list of pairs that represent
+the start and end offsets in the string that you want highlighted.
+
+.. literalinclude:: ../snippets/using_highlights_1.py
+
+.. figure:: ../snippets/using_highlights_1.png
+
+Every list of pairs that is passed in is considered a highlighting layer
+and gets a new color. Where layers overlap this is indicated by applying:
+
+- bold (two layers overlap),
+- reverse (three layers overlap),
+- bold and reverse (four layers overlap).
+
+Four layers is the maximum, because after that there is no further
+distinction possible. See :data:`ansicolor.demos.demo_highlight` for an
+exhaustive example.