Create FAQ document with explanation about Thrift API

3 files changed, 55 insertions, 46 deletions

diff --git a/doc/faq.rst b/doc/faq.rst
new file mode 100644
index 0000000..e576581
--- /dev/null
+++ b/doc/faq.rst
@@ -0,0 +1,53 @@
+==========================
+Frequently asked questions
+==========================
+
+
+Why not use the Thrift API directly?
+====================================
+
+While the HBase Thrift API can be used directly from Python using (automatically
+generated) HBase Thrift service classes, application code doing so is very
+verbose, cumbersome to write, and hence error-prone. The reason for this is that
+the HBase Thrift API is a flat, language-agnostic interface API closely tied to
+the RPC going over the wire-level protocol. In practice, this means that
+applications using Thrift directly need to deal with many imports, sockets,
+transports, protocols, clients, Thrift types and mutation objects. For instance,
+look at the code required to connect to HBase and store two values::
+
+   from thrift import Thrift
+   from thrift.transport import TSocket, TTransport
+   from thrift.protocol import TBinaryProtocol
+
+   from hbase import ttypes
+   from hbase.Hbase import Client, Mutation
+
+   sock = TSocket.TSocket('hostname', 9090)
+   transport = TTransport.TBufferedTransport(sock)
+   protocol = TBinaryProtocol.TBinaryProtocol(transport)
+   client = Client(protocol)
+   transport.open()
+
+   mutations = [Mutation(column='family:qual1', value='value1'),
+                Mutation(column='family:qual2', value='value2')]
+   client.mutateRow('table-name', 'row-key', mutations)
+
+:pep:`20` taught us that simple is better than complex, and as you can see,
+Thrift is certainly complex. HappyBase hides all the Thrift cruft below a
+friendly API. The resulting application code will be cleaner, more productive
+to write, and more maintainable. With HappyBase, the example above can be
+simplified to this::
+
+   import happybase
+
+   connection = happybase.Connection('hostname')
+   table = connection.table('table-name')
+   table.put('row-key', {'family:qual1': 'value1',
+                         'family:qual2': 'value2'})
+
+If you're not convinced and still think the Thrift API is not that bad, please
+try to accomplish some other common tasks, e.g. retrieving rows and scanning
+over a part of a table, and compare that to the HappyBase equivalents. If
+you're still not convinced by then, we're sorry to inform you that HappyBase is
+not the project for you, and we wish you all of luck maintaining your code ‒ or
+is it just Thrift boilerplate?
diff --git a/doc/index.rst b/doc/index.rst
index 3be5298..7d787cf 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -29,6 +29,7 @@ HappyBase
    news
    development
    todo
+   faq
    license
 
 
diff --git a/doc/introduction.rst b/doc/introduction.rst
index 2e40407..372ad8f 100644
--- a/doc/introduction.rst
+++ b/doc/introduction.rst
@@ -36,52 +36,7 @@ The example below illustrates basic usage of the library. The :doc:`tutorial
 Below the surface, HappyBase uses the `Python Thrift library
 <http://pypi.python.org/pypi/thrift>`_ to connect to HBase using its `Thrift
 <http://thrift.apache.org/>`_ gateway, which is included in the standard HBase
-0.9x releases. While this HBase Thrift API can be used directly from Python
-using (automatically generated) HBase Thrift service classes, application code
-doing so is very verbose, cumbersome to write, and hence error-prone. The
-reason for this is that the HBase Thrift API is a flat, language-agnostic
-interface API closely tied to the RPC going over the wire-level protocol. In
-practice, this means that applications using Thrift directly need to deal with
-many imports, sockets, transports, protocols, clients, Thrift types and
-mutation objects. For instance, look at the code required to connect to HBase
-and store two values::
-
-   from thrift import Thrift
-   from thrift.transport import TSocket, TTransport
-   from thrift.protocol import TBinaryProtocol
-
-   from hbase import ttypes
-   from hbase.Hbase import Client, Mutation
-
-   sock = TSocket.TSocket('hostname', 9090)
-   transport = TTransport.TBufferedTransport(sock)
-   protocol = TBinaryProtocol.TBinaryProtocol(transport)
-   client = Client(protocol)
-   transport.open()
-
-   mutations = [Mutation(column='family:qual1', value='value1'),
-                Mutation(column='family:qual2', value='value2')]
-   client.mutateRow('table-name', 'row-key', mutations)
-
-:pep:`20` taught us that simple is better than complex, and as you can see,
-Thrift is certainly complex. HappyBase hides all the Thrift cruft below a
-friendly API. The resulting application code will be cleaner, more productive
-to write, and more maintainable. With HappyBase, the example above can be
-simplified to this::
-
-   import happybase
-
-   connection = happybase.Connection('hostname')
-   table = connection.table('table-name')
-   table.put('row-key', {'family:qual1': 'value1',
-                         'family:qual2': 'value2'})
-
-If you're not convinced and still think the Thrift API is not that bad, please
-try to accomplish some other common tasks, e.g. retrieving rows and scanning
-over a part of a table, and compare that to the HappyBase equivalents. If
-you're still not convinced by then, we're sorry to inform you that HappyBase is
-not the project for you, and we wish you all of luck maintaining your code ‒ or
-is it just Thrift boilerplate?
+0.9x releases.
 
 
 .. rubric:: Next steps