README: update for 4.0

README.rst

@@ -2,6 +2,12 @@
 Clize
 *****
 
+.. image:: https://readthedocs.org/projects/clize/badge/?version=stable
+   :target: http://clize.readthedocs.io/en/stable/?badge=stable
+   :alt: Documentation Status
+.. image:: https://readthedocs.org/projects/clize/badge/?version=latest
+   :target: http://clize.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status
 .. image:: https://badges.gitter.im/Join%20Chat.svg
    :alt: Join the chat at https://gitter.im/epsy/clize
    :target: https://gitter.im/epsy/clize?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
@@ -10,10 +16,20 @@ Clize
 .. image:: https://coveralls.io/repos/epsy/clize/badge.svg?branch=master
     :target: https://coveralls.io/r/epsy/clize?branch=master
 
-Clize procedurally turns your functions into convenient command-line
-interfaces.
+Clize is an argument parser for `Python <https://www.python.org/>`_.  You can
+use Clize as an alternative to ``argparse`` if you want an even easier way to
+create command-line interfaces.
 
-For instance:
+.. rubric:: With Clize, you can:
+
+* Create command-line interfaces by creating functions and passing them to
+  `clize.run`.
+* Enjoy a CLI automatically created from your functions' parameters.
+* Bring your users familiar ``--help`` messages generated from your docstrings.
+* Reuse functionality across multiple commands using decorators.
+* Extend Clize with new parameter behavior.
+
+.. rubric:: Here's an example:
 
 .. code-block:: python
 
@@ -22,9 +38,8 @@ For instance:
     def hello_world(name=None, *, no_capitalize=False):
         """Greets the world or the given name.
 
-        name: If specified, only greet this person.
-
-        no_capitalize: Don't capitalize the given name.
+        :param name: If specified, only greet this person.
+        :param no_capitalize: Don't capitalize the given name.
         """
         if name:
             if not no_capitalize:
@@ -35,6 +50,9 @@ For instance:
     if __name__ == '__main__':
         run(hello_world)
 
+Python 2.7 is supported through `decorators
+<http://clize.readthedocs.io/en/stable/reference.html#named-param-py2>`_.
+
 The python code above can now be used on the command-line as follows:
 
 .. code-block:: console
@@ -60,4 +78,4 @@ The python code above can now be used on the command-line as follows:
     $ python3 hello.py dave --no-capitalize
     Hello dave!
 
-You can find the documentation at: http://clize.readthedocs.io/
+You can find the documentation and tutorials at http://clize.readthedocs.io/