Improve create_table docs; also mention in tutorial

2 files changed, 51 insertions, 16 deletions

diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index 439307e..52f142a 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -46,18 +46,17 @@ manually using :py:meth:`Connection.open`::
    # before first use:
    connection.open()
 
-The :py:class:`Connection` class provides various methods to interact with
+The :py:class:`Connection` class provides the main entry point to interact with
 HBase. For instance, to list the available tables, use
 :py:meth:`Connection.tables`::
 
    print connection.tables()
 
-The :py:class:`Connection` class offers various other methods to interact with
-HBase, mostly to perform system management tasks like creating, enabling and
-disabling tables. See the :doc:`API documentation <api>` for the
-:py:class:`Connection` class contains more information. This tutorial does not
-cover those since it's more likely you are already using the HBase shell for
-these system management tasks.
+Most other methods on the :py:class:`Connection` class are intended for system
+management tasks like creating, dropping, enabling and disabling tables. See the
+:doc:`API documentation <api>` for the :py:class:`Connection` class contains
+more information. This tutorial does not cover those since it's more likely you
+are already using the HBase shell for these system management tasks.
 
 
 Working with tables
@@ -65,9 +64,25 @@ Working with tables
 
 The :py:class:`Table` class provides the main API to retrieve and manipulate
 data in HBase. In the example above, we already asked for the available tables
-using the :py:meth:`Connection.tables` method. The next step is to obtain a
-:py:class:`.Table` instance to work with. Obtain a table by calling
-:py:meth:`Connection.table`, passing it the table name::
+using the :py:meth:`Connection.tables` method. If there weren't any tables yet,
+you can create a new one using :py:meth:`Connection.create_table`::
+
+   connection.create_table(
+       'mytable',
+       {'cf1': dict(max_versions=10),
+        'cf2': dict(max_versions=1, block_cache_enabled=False),
+        'cf3': dict(),  # use defaults
+       }
+   )
+
+.. note::
+
+    The HBase shell is often a better alternative for many HBase administration
+    tasks, since the shell is more powerful compared to the limited Thrift API
+    that HappyBase uses.
+
+The next step is to obtain a :py:class:`.Table` instance to work with. Simply
+call :py:meth:`Connection.table`, passing it the table name::
 
    table = connection.table('mytable')
 
diff --git a/happybase/api.py b/happybase/api.py
index d7cbcc3..1756d83 100644
--- a/happybase/api.py
+++ b/happybase/api.py
@@ -206,12 +206,32 @@ class Connection(object):
         :param str name: The table name
         :param dict families: The name and options for each column family
 
-        The `families` parameter is a dictionary mapping column family names to
-        a dictionary containing the options for this column family. See
-        ColumnDescriptor in the Thrift API for the supported options, but note
-        that the names should be provided in Python style, and not in camel
-        case notation, for example `time_to_live` (not `timeToLive`) and
-        `max_versions` (not `maxVersions`).
+        The `families` parameter is a dictionary mapping column family
+        names to a dictionary containing the options for this column
+        family, e.g.
+
+        ::
+
+            families = {
+                'cf1': dict(max_versions=10),
+                'cf2': dict(max_versions=1, block_cache_enabled=False),
+                'cf3': dict(),  # use defaults
+            }
+            connection.create_table('mytable', families)
+
+        These options correspond to the ColumnDescriptor structure in
+        the Thrift API, but note that the names should be provided in
+        Python style, not in camel case notation, e.g. `time_to_live`,
+        not `timeToLive`. The following options are supported:
+
+        * ``max_versions`` (`int`)
+        * ``compression`` (`str`)
+        * ``in_memory`` (`bool`)
+        * ``bloom_filter_type`` (`str`)
+        * ``bloom_filter_vector_size`` (`int`)
+        * ``bloom_filter_nb_hashes`` (`int`)
+        * ``block_cache_enabled`` (`bool`)
+        * ``time_to_live`` (`int`)
         """
         name = self._table_name(name)
         if not isinstance(families, dict):