Documented HStoreField

docs/features.md

@@ -0,0 +1,41 @@
+# Overview
+
+# HStoreField
+`psqlextra.fields.HStoreField` is based on Django's [HStoreField](https://docs.djangoproject.com/en/1.10/ref/contrib/postgres/fields/#hstorefield) and therefor supports everything Django does natively, plus more.
+
+## Constraints
+### uniqueness
+The `uniqueness` constraint can be added on one or more `hstore` keys, similar to how a `UNIQUE` constraint can be added to a column. Setting this option causes unique indexes to be created on the specified keys.
+
+You can specify a `list` of strings to specify the keys that must be marked as unique:
+
+    from psqlextra.fields import HStoreField
+    from psqlextra.models import PostgresModel
+
+    class MyModel(PostgresModel):
+        myfield = HStoreField(uniqueness=['key1']
+
+    MyModel.objects.create(myfield={'key1': 'value1'})
+    MyModel.objects.create(myfield={'key1': 'value1'})
+
+The second `create` call will fail with a [IntegrityError](https://docs.djangoproject.com/en/1.10/ref/exceptions/#django.db.IntegrityError) because there's already a row with `key1=value1`.
+
+Uniqueness can also be enforced "together", similar to Django's [unique_together](https://docs.djangoproject.com/en/1.10/ref/models/options/#unique-together) by specifying a tuple of fields rather than a single string:
+
+    myfield = HStoreField(uniqueness=[('key1', 'key2'), 'key3])
+
+In the example above, `key1` and `key2` must unique **together**, and `key3` must unique on its own. By default, none of the keys are marked as "unique".
+
+### required
+The `required` option can be added to ensure that the specified `hstore` keys are set for every row. This is similar to a `NOT NULL` constraint on a column. You can specify a list of `hstore` keys that are required:
+
+    from psqlextra.fields import HStoreField
+    from psqlextra.models import PostgresModel
+
+    class MyModel(PostgresModel):
+        myfield = HStoreField(required=['key1'])
+
+    mymodel.objects.create(myfield={'key1': none})
+    MyModel.objects.create(myfield={'key2': 'value1'})
+
+Both calls to `create` would fail in the example above since they do not provide a non-null value for `key1`. By default, none of the keys are required.

docs/index.md

@@ -4,7 +4,7 @@ django-postgres-extra aims to make all of PostgreSQL's awesome features availabl
 
 With seamless we mean that any features we add will work truly seamlessly. You should not have to manually modify your migrations to work with fields and objects provided by this package.
 
-## Features
+## PostgreSQL features
 We are currently aiming on having the following features available:
 
 * [hstore](https://www.postgresql.org/docs/9.1/static/hstore.html)

mkdocs.yml

@@ -1 +1,4 @@
 site_name: django-postgres-extra
+pages:
+- Home: index.md
+- Features: features.md