improved docs

Author: wolph

README.rst

@@ -1,5 +1,6 @@
+##############################################################################
 Text progress bar library for Python.
-=====================================
+##############################################################################
 
 Travis status:
 
@@ -11,8 +12,9 @@ Coverage:
 .. image:: https://coveralls.io/repos/WoLpH/python-progressbar/badge.png?branch=master
   :target: https://coveralls.io/r/WoLpH/python-progressbar?branch=master
 
+******************************************************************************
 Introduction
-------------
+******************************************************************************
 
 .. highlights::
 
@@ -48,8 +50,9 @@ of widgets:
 The progressbar module is very easy to use, yet very powerful. It will also
 automatically enable features like auto-resizing when the system supports it.
 
+******************************************************************************
 Links
------
+******************************************************************************
 
 * Documentation
     - http://progressbar-2.readthedocs.org/en/latest/
@@ -62,3 +65,73 @@ Links
 * My blog
     - http://w.wol.ph/
 
+******************************************************************************
+Usage
+******************************************************************************
+
+There are many ways to use Python Progressbar, you can see a few basic examples
+here but there are many more in the :doc:`examples` file.
+
+Wrapping an iterable
+==============================================================================
+::
+
+   import time
+   import progressbar
+
+   bar = progressbar.ProgressBar()
+   for i in bar(range(100)):
+       time.sleep(0.02)
+
+Context wrapper
+==============================================================================
+::
+
+   import time
+   import progressbar
+
+   with progressbar.ProgressBar(max_value=10) as bar:
+       for i in range(10):
+           time.sleep(0.1)
+           bar.update(i)
+
+Combining progressbars with print output
+==============================================================================
+::
+
+    import time
+    import progressbar
+
+    bar = progressbar.ProgressBar(redirect_stdout=True)
+    for i in range(100):
+        print 'Some text', i
+        time.sleep(0.1)
+        bar.update(i)
+
+Progressbar with unknown length
+==============================================================================
+::
+
+    import time
+    import progressbar
+
+    bar = progressbar.ProgressBar(max_value=progressbar.UnknownLength)
+    for i in range(20):
+        time.sleep(0.1)
+        bar.update(i)
+
+Bar with custom widgets
+==============================================================================
+::
+
+    import time
+    import progressbar
+
+    bar = progressbar.ProgressBar(widgets=[
+        ' [', progressbar.Timer(), '] ',
+        progressbar.Bar(),
+        ' (', progressbar.ETA(), ') ',
+    ])
+    for i in bar(range(20)):
+        time.sleep(0.1)
+

docs/index.rst

@@ -9,7 +9,6 @@ Contents
 .. toctree::
    :maxdepth: 4
 
-   usage
    examples
    contributing
    history