docs: adding "Features" document

Comprehensive list of gluetool's features, complete with examples and
recordings.

.gitignore

@@ -16,6 +16,7 @@ dist
 **/.coverage*
 
 # auto-generated *.rst docs
+docs/source/modules.rst
 docs/source/gluetool.*
 
 # Ansible "retry" files

docs/source/conf.py

@@ -25,6 +25,7 @@
 import sys
 
 import sphinx.ext.autodoc
+import sphinx.ext.todo
 import sphinx.environment
 import sphinx_rtd_theme
 from docutils.utils import get_source_line
@@ -44,6 +45,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.coverage',
+    'sphinx.ext.todo',
     'sphinx.ext.viewcode'
 ]
 
@@ -85,7 +87,7 @@
 pygments_style = 'sphinx'
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+todo_include_todos = True
 
 
 # -- Options for HTML output ----------------------------------------------
@@ -107,6 +109,9 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = []
 
+html_logo = 'gluetool-logo-100.png'
+html_favicon = 'favicon.ico'
+
 
 # -- Options for HTMLHelp output ------------------------------------------
 

docs/source/features.rst

@@ -0,0 +1,35 @@
+``gluetool`` features
+=====================
+
+A comprehensive list of ``gluetool`` features, available helpers, tricks and tips. All the ways ``gluetool`` have to help module developers.
+
+.. include:: features/core.rst
+.. include:: features/help.rst
+.. include:: features/logging.rst
+.. include:: features/colors.rst
+.. include:: features/sentry.rst
+.. include:: features/utils.rst
+
+
+----
+
+Tool
+----
+
+.. todo::
+
+  Features yet to describe:
+
+  * reusable heart of gluetool
+  * config file on system level, user level or in a local dir
+
+
+----
+
+.. todo::
+
+  Features yet to describe:
+
+  * custom pylint checkers
+  * option names
+  * shared function definitions

docs/source/features/colors.rst

@@ -0,0 +1,96 @@
+Colorized output
+----------------
+
+``gluetool`` uses awesome `colorama <https://pypi.python.org/pypi/colorama>`_ library to enhance many of its outputs with colors. This is done in a transparent way, when developer does not need to think about it, and user can control this feature with a single option.
+
+
+Control
+~~~~~~~
+
+Color support is disabled by default, and can be turned on using ``--color`` option:
+
+.. raw:: html
+
+   <script src="https://asciinema.org/a/GhsulmjcL5FjXf5uA3XGE4sLi.js" id="asciicast-GhsulmjcL5FjXf5uA3XGE4sLi" async></script>
+
+
+If ``colorama`` package is **not** installed, color support cannot be turned on. If user tries to do that, ``gluetool`` will emit a warning:
+
+.. raw:: html
+
+   <script src="https://asciinema.org/a/NhorAwOzY3NiBhlT1QSXxpkqL.js" id="asciicast-NhorAwOzY3NiBhlT1QSXxpkqL" async></script>
+
+.. note::
+
+   As of now, ``colorama`` is ``gluetool``'s hard requirement, therefore it should not be possible - at least out of the box - to run ``gluetool`` wihout having ``colorama`` installed. However, this may change in the future, leaving this support up to user decision.
+
+To control this feature programatically, see :py:func:`gluetool.color.switch`.
+
+.. todo::
+
+   * ``seealso``:
+
+     * how to specify options
+
+Colorized logs
+~~~~~~~~~~~~~~
+
+Messages, logged on the terminal, are colorized based on their level:
+
+.. raw:: html
+
+   <script src="https://asciinema.org/a/170112.js" id="asciicast-170112" async></script>
+
+``DEBUG`` log level inherits default text color of your terminal, while, for example, ``ERROR`` is highlighted by being red, and ``INFO`` level is printed with nice, comforting green.
+
+.. todo::
+
+   * ``seealso``:
+
+     * logging
+
+Colorized help
+~~~~~~~~~~~~~~
+
+``gluetool`` uses reStructuredText (reST) to document modules, shared functions, opitons and other things, and to make the help texts even more readable, formatting, provided by reST, is enhanced with colors, to help users orient and focus on important information.
+
+.. raw:: html
+
+   <script src="https://asciinema.org/a/170118.js" id="asciicast-170118" async></script>
+
+.. todo::
+
+   * ``seealso``:
+
+     * generic help
+     * module help
+     * option help
+
+
+.. _colors-in-templates:
+
+Colors in templates
+~~~~~~~~~~~~~~~~~~~
+
+Color support is available for templates as well, via :py:func:`style <gluetool.color._style_colors>` filter.
+
+Example:
+
+.. code-block:: python
+   :emphasize-lines: 6
+
+   import gluetool
+
+   gluetool.log.Logging.create_logger()
+   gluetool.color.switch(True)
+
+   print gluetool.utils.render_template('{{ "foo" | style(fg="red", bg="green") }}')
+
+.. raw:: html
+
+   <script src="https://asciinema.org/a/170123.js" id="asciicast-170123" async></script>
+
+.. seealso::
+
+   :ref:`rendering-templates`
+       for more information about rendering templates with ``gluetool``.