From b501d22ad94ec098d554db015a7d9f66949ceab2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Mand=C3=A1k?= <lukas.mandak@yandex.com>
Date: Fri, 19 Jun 2015 22:27:16 +0200
Subject: [PATCH] Moved `hints` documentation to Configuration section. Added a
 few basic examples.

---
 docs/configuration.rst     | 69 ++++++++++++++++++++++++++++++++++++++
 i3pystatus/core/modules.py | 23 +------------
 2 files changed, 70 insertions(+), 22 deletions(-)

diff --git a/docs/configuration.rst b/docs/configuration.rst
index fb47b96..fe02994 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -298,3 +298,72 @@ The settings can be of different types, namely
   elements are passed as arguments to the callable
 - again a special case of the above: just a callable, no parameters
 - a string which is run in a shell
+
+.. _hints:
+
+Hints
+-----
+
+Hints are additional parameters used to customize output of a module.
+They give you access to all attributes supported by `i3bar protocol
+<http://i3wm.org/docs/i3bar-protocol.html#_blocks_in_detail>`_.
+
+Hints are available as ``hints`` setting in all modules and its value should be
+a dictionary or ``None``.
+An attribute defined in ``hints`` will be applied only if module output does not
+contain attribute with the same name already.
+
+Some possible uses for these attributes are:
+
+*   `min_width` and `align` can be used to set minimal width of output and
+    align the text if its width is shorter than `minimal_width`.
+*   `separator` and `separator_block_width` can be used to remove the
+    vertical bar that is separating modules.
+*   `markup` can be set to `"none"` or `"pango"`.
+    `Pango markup
+    <https://developer.gnome.org/pango/stable/PangoMarkupFormat.html>`_
+    provides additional formatting options for drawing rainbows and other
+    fancy stuff.
+
+Here is an example with the :py:class:`.Network` module.
+Pango markup is used to keep the ESSID green at all times while the
+recieved/sent part is changing color depending on the amount of traffic.
+
+  .. code:: python
+
+        status.register("network",
+            interface = "wlp2s0",
+            hints = {"markup": "pango"},
+            format_up = "<span color=\"#00FF00\">{essid}</span> {bytes_recv:6.1f}KiB {bytes_sent:5.1f}KiB",
+            format_down = "",
+            dynamic_color = True,
+            start_color = "#00FF00",
+            end_color = "#FF0000",
+            color_down = "#FF0000",
+            upper_limit = 800.0,
+            )
+
+Or you can use pango to customize the color of ``status`` setting in
+:py:class:`.NowPlaying` and :py:class:`.MPD` modules.
+
+    .. code:: python
+
+        ...
+        hints = {"markup": "pango"},
+        status = {
+            "play": "▶",
+            "pause": "<span color=\"orange\">▶</span>",
+            "stop": "<span color=\"red\">◾</span>",
+        },
+        ...
+
+Or make two modules look like one.
+
+    .. code:: python
+
+        status.register("text",
+            text = "shmentarianism is a pretty long word.")
+        status.register("text",
+            hints = {"separator": False, "separator_block_width": 0},
+            text = "Antidisestabli",
+            color="#FF0000")
diff --git a/i3pystatus/core/modules.py b/i3pystatus/core/modules.py
index 859c7b9..4c8fa54 100644
--- a/i3pystatus/core/modules.py
+++ b/i3pystatus/core/modules.py
@@ -13,7 +13,7 @@ class Module(SettingsBase):
         ('on_rightclick', "Callback called on right click (see :ref:`callbacks`)"),
         ('on_upscroll', "Callback called on scrolling up (see :ref:`callbacks`)"),
         ('on_downscroll', "Callback called on scrolling down (see :ref:`callbacks`)"),
-        ('hints', "Additional output blocks for module output (dict)"),
+        ('hints', "Additional output blocks for module output (see :ref:`hints`)"),
     )
 
     on_leftclick = None
@@ -22,27 +22,6 @@ class Module(SettingsBase):
     on_downscroll = None
 
     hints = {"markup": "none"}
-    """
-    A dictionary containing additional output blocks used to customize output of
-    a module.
-
-    Blocks will be applied only if `self.output` does not contain a block with
-    the same name already.
-
-    All blocks are described in `i3bar protocol documentation
-    <http://i3wm.org/docs/i3bar-protocol.html#_blocks_in_detail>`_
-    but it is recommended to use only the following blocks:
-
-    * `min_width` and `align` blocks are used to set minimal width of output and
-      text aligment if text width is shorter than minimal width.
-    * `separator` and `separator_block_width` blocks are used to remove the
-      vertical bar that is separating modules.
-    * `markup` block can be set to `"none"` or `"pango"`.
-      `Pango markup
-      <https://developer.gnome.org/pango/stable/PangoMarkupFormat.html>`_
-      provides additional formatting options for advanced users.
-
-    """
 
     def registered(self, status_handler):
         """Called when this module is registered with a status handler"""