Merge branch 'docs'

Pull in the documentation branch with Sphinx docs for the begins
project.

docs/_templates/layout.html

@@ -0,0 +1,5 @@
+{% extends "!layout.html" %}
+{% block sidebartoc %}
+    <h3>{{ _('Table Of Contents') }}</h3>
+    {{ toctree(includehidden=True) }}
+{% endblock %}

docs/api.rst

@@ -0,0 +1,21 @@
+==============
+The begins API
+==============
+
+.. automodule:: begin
+   :members:
+   :undoc-members:
+
+Utilities
+=========
+
+.. automodule:: begin.utils
+   :members:
+   :undoc-members:
+
+Help Formatters
+===============
+
+.. automodule:: begin.formatters
+   :members:
+   :undoc-members:

docs/examples/advanced.py

@@ -0,0 +1,17 @@
+import begin
+import logging
+
+@begin.subcommand
+def hello(name):
+    "Say hello"
+    logging.info("Hello {0}".format(name))
+
+@begin.subcommand
+def goodbye(name):
+    "Say goodbye"
+    logging.info("Goodbye {0}".format(name))
+
+@begin.start
+@begin.logging
+def main():
+    "Greetings and salutations"

docs/examples/flask_quickstart.py

@@ -7,7 +7,7 @@
 def hello_world():
     return 'Hello World!'
 
-@begin.start(env_prefix='WEB_')
-@begin.convert(port=int, debug=begin.utils.tobool)
+@begin.start(auto_convert=True, env_prefix='WEB_')
+@begin.logging
 def main(host='127.0.0.1', port=8080, debug=False):
     app.run(host=host, port=port, debug=debug)

docs/examples/rawhelp.py

@@ -0,0 +1,17 @@
+import begin
+my_formatter = begin.formatters.compose(begin.formatters.RawDescription)
+
+@begin.subcommand
+def sub():
+    """Such    text
+                Very whitespace
+            So exact
+    """
+
+@begin.start(formatter_class=my_formatter)
+def main():
+    """Plain text formatting for this help:
+    - how does it look?
+    Params:
+        foo is yummy... 
+    """

docs/examples/shell.py

@@ -0,0 +1,23 @@
+import shutil
+import begin
+
+begin.subcommand(shutil.copy)
+begin.subcommand(shutil.copy2)
+begin.subcommand(shutil.copyfile)
+begin.subcommand(shutil.copymode)
+begin.subcommand(shutil.copystat)
+begin.subcommand(shutil.copytree)
+begin.subcommand(shutil.move)
+begin.subcommand(shutil.rmtree)
+
+# Patch in doc before the func is wrapped by begin.start
+def patch_doc(doc):
+   def decorate(func):
+       func.__doc__ = doc
+       return func
+   return decorate
+
+@begin.start
+@patch_doc(shutil.__doc__)
+def main():
+   pass