Improve documentation

aioriak/datatypes/map.py

@@ -78,7 +78,7 @@ class Map(Mapping, Datatype):
         del map[('emails', 'set')]
 
     Convenience accessors exist that partition the map's keys by
-    datatype and implement the :class:`~collections.Mapping`
+    datatype and implement the collections.Mapping
     behavior as well as supporting deletion::
 
         map.sets['emails']

docs/bucket.rst

@@ -0,0 +1,170 @@
+.. _bucket_types:
+
+======================
+Buckets & Bucket Types
+======================
+
+.. currentmodule:: aioriak.bucket
+
+**Buckets** are both namespaces for the key-value pairs you store in
+Riak, and containers for properties that apply to that namespace. In
+older versions of Riak, this was the only logical organization
+available. Now a higher-level collection called a **Bucket Type** can
+group buckets together. They allow for efficiently setting properties
+on a group of buckets at the same time.
+
+Unlike buckets, Bucket Types must be `explicitly created
+<http://docs.basho.com/riak/2.0.0/dev/advanced/bucket-types/#Managing-Bucket-Types-Through-the-Command-Line>`_
+and activated before being used::
+
+   riak-admin bucket-type create n_equals_1 '{"props":{"n_val":1}}'
+   riak-admin bucket-type activate n_equals_1
+
+Bucket Type creation and activation is only supported via the
+``riak-admin bucket-type`` command-line tool. Riak 2.0 does not
+include an API to perform these actions, but the Python client *can*
+:meth:`retrieve <BucketType.get_properties>` and :meth:`set
+<BucketType.set_properties>` bucket-type properties.
+
+If Bucket Types are not specified, the *default* bucket
+type is used.  These buckets should be created via the :meth:`bucket()
+<aioriak.client.RiakClient.bucket>` method on the client object, like so::
+
+    import riak
+
+    async def go():
+        client = await riak.RiakClient.create()
+        mybucket = client.bucket('mybucket')
+
+Buckets with a user-specified Bucket Type can also be created via the same
+:meth:`bucket()<aioriak.client.RiakClient.bucket>` method with
+an additional parameter or explicitly via
+:meth:`bucket_type()<aioriak.client.RiakClient.bucket_type>`::
+
+    othertype = client.bucket_type('othertype')
+    otherbucket = othertype.bucket('otherbucket')
+
+    # Alternate way to get a bucket within a bucket-type
+    mybucket = client.bucket('mybucket', bucket_type='mybuckettype')
+
+For more detailed discussion, see `Using Bucket Types
+<http://docs.basho.com/riak/2.0.0/dev/advanced/bucket-types/>`_.
+
+--------------
+Bucket objects
+--------------
+
+.. autoclass:: Bucket
+
+    .. automethod:: __init__ 
+
+    .. attribute:: name
+
+        The name of the bucket, a string.
+
+    .. attribute:: bucket_type
+
+        The parent :class:`BucketType` for the bucket.
+
+    .. autoattribute:: resolver
+
+-----------------
+Bucket properties
+-----------------
+
+Bucket properties are flags and defaults that apply to all keys in the
+bucket.
+
+.. autocomethod:: Bucket.get_properties
+.. autocomethod:: Bucket.set_properties
+.. autocomethod:: Bucket.get_property
+.. autocomethod:: Bucket.set_property
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Shortcuts for common properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some of the most commonly-used bucket properties are exposed as object
+properties as well. The getters and setters simply call
+:meth:`Bucket.get_property` and :meth:`Bucket.set_property`
+respectively.
+
+.. autoattribute:: Bucket.allow_mult
+
+-----------------
+Working with keys
+-----------------
+
+The primary purpose of buckets is to act as namespaces for keys. As
+such, you can use the bucket object to create, fetch and delete
+:class:`objects <aioriak.riak_object.RiakObject>`.
+
+.. autocomethod:: Bucket.new
+.. autocomethod:: Bucket.get
+.. autocomethod:: Bucket.delete
+
+-------------
+Serialization
+-------------
+
+Similar to :class:`RiakClient <aioriak.client.RiakClient>`, buckets can
+register custom transformation functions for media-types. When
+undefined on the bucket, :meth:`Bucket.get_encoder` and
+:meth:`Bucket.get_decoder` will delegate to the client associated
+with the bucket.
+
+.. automethod:: Bucket.get_encoder
+.. automethod:: Bucket.set_encoder
+.. automethod:: Bucket.get_decoder
+.. automethod:: Bucket.set_decoder
+
+------------
+Listing keys
+------------
+
+Shortcuts for :meth:`RiakClient.get_keys()
+<aioriak.client.RiakClient.get_keys>` are exposed on the bucket
+object. The same admonitions for these operation apply.
+
+.. autocomethod:: Bucket.get_keys
+
+-------------------
+Bucket Type objects
+-------------------
+
+.. autoclass:: BucketType
+
+    .. automethod:: __init__
+
+    .. attribute:: name
+
+        The name of the Bucket Type, a string.
+
+.. automethod:: BucketType.is_default
+
+.. automethod:: BucketType.bucket
+
+----------------------
+Bucket Type properties
+----------------------
+
+Bucket Type properties are flags and defaults that apply to all buckets in the
+Bucket Type.
+
+.. autocomethod:: BucketType.get_properties
+.. autocomethod:: BucketType.set_properties
+.. autocomethod:: BucketType.get_property
+.. autocomethod:: BucketType.set_property
+.. attribute:: BucketType.datatype
+
+    The assigned datatype for this bucket type, if present.
+
+---------------
+Listing buckets
+---------------
+
+Shortcut for :meth:`RiakClient.get_buckets()
+<aioriak.client.RiakClient.get_buckets>` is exposed on the bucket
+type object.  This is similar to `Listing keys`_ on buckets.
+
+.. autocomethod:: BucketType.get_buckets

docs/client.rst

@@ -1,6 +1,6 @@
 .. highlight:: python
 
-.. module:: aioriak.client
+.. currentmodule:: aioriak.client
 
 ====================
 Client & Connections
@@ -27,7 +27,6 @@ ports. The below instantiation statements are all equivalent::
 Client objects
 --------------
 
-.. currentmodule:: aioriak.client
 .. autoclass:: RiakClient
 
     .. autoattribute:: resolver
@@ -54,3 +53,43 @@ that will proxy operations to the called client.
 
 .. automethod:: RiakClient.bucket_type
 .. automethod:: RiakClient.bucket
+
+----------------------
+Bucket Type Operations
+----------------------
+
+.. autocomethod:: RiakClient.get_bucket_type_props
+.. autocomethod:: RiakClient.set_bucket_type_props
+
+-----------------
+Bucket Operations
+-----------------
+
+.. autocomethod:: RiakClient.get_bucket_props
+.. autocomethod:: RiakClient.set_bucket_props
+.. autocomethod:: RiakClient.get_keys
+
+--------------------
+Key-level Operations
+--------------------
+
+.. autocomethod:: RiakClient.get
+.. autocomethod:: RiakClient.put
+.. autocomethod:: RiakClient.delete
+.. autocomethod:: RiakClient.fetch_datatype
+.. autocomethod:: RiakClient.update_datatype
+
+-------------
+Serialization
+-------------
+
+The client supports automatic transformation of Riak responses into
+Python types if encoders and decoders are registered for the
+media-types. Supported by default are ``application/json`` and
+``text/plain``.
+
+.. autofunction:: default_encoder
+.. automethod:: RiakClient.get_encoder
+.. automethod:: RiakClient.set_encoder
+.. automethod:: RiakClient.get_decoder
+.. automethod:: RiakClient.set_decoder

docs/conf.py

@@ -62,9 +62,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.0.2'
+version = '0.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.0.2'
+release = '0.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -364,3 +364,6 @@
 # epub_use_index = True
 
 # Custom configs
+intersphinx_mapping = {
+    'riak': ('https://basho.github.io/riak-python-client/', None)
+}