Add sphinx based docs

docs/source/localized_value.rst

@@ -0,0 +1,79 @@
+Working with localized values
+=============================
+
+.. note::
+
+    All examples below assume a model declared like this:
+
+    .. code-block:: python
+
+        from localized_fields.models import LocalizedModel
+        from localized_fields.fields import LocalizedField
+
+
+        class MyModel(LocalizedModel):
+            title = LocalizedField()
+
+Localized content is represented by ``localized_fields.value.LocalizedValue``. Which is essentially a dictionary where the key is the language and the value the content in the respective language.
+
+.. code-block:: python
+
+    from localized_fields.value import LocalizedValue
+
+    obj = MyModel.objects.first()
+    assert isistance(obj.title, LocalizedValue) # True
+
+
+With fallback
+-------------
+
+.. seealso::
+
+    Configure :ref:`LOCALIZED_FIELDS_FALLBACKS <LOCALIZED_FIELDS_FALLBACKS>` to control the fallback behaviour.
+
+
+Active language
+***************
+
+.. code-block:: python
+
+    # gets content in Arabic, falls back to next language
+    # if not availble
+    translation.activate('ar')
+    obj.title.translate()
+
+    # alternative: cast to string
+    title_ar = str(obj.title)
+
+
+Specific language
+*****************
+
+.. code-block:: python
+
+    # gets content in Arabic, falls back to next language
+    # if not availble
+    obj.title.translate('ar')
+
+
+Without fallback
+----------------
+
+Specific language
+*****************
+
+.. code-block:: python
+
+    # gets content in Dutch, None if not available
+    # no fallback to secondary languages here!
+    obj.title.nl
+
+
+Specific language dynamically
+*****************************
+
+.. code-block:: python
+
+    # gets content in Dutch, None if not available
+    # no fallback to secondary languages here!
+    obj.title.get('nl')