From ff74a74a15185300b049f4fca3a8c1dd4e594f30 Mon Sep 17 00:00:00 2001
From: Jacek Tomaszewski <jacek.tomek@gmail.com>
Date: Mon, 30 Dec 2013 20:06:59 +0100
Subject: [PATCH] Add TranslationOptions fields reference to docs.

---
 docs/modeltranslation/forms.rst        |  2 ++
 docs/modeltranslation/registration.rst | 45 ++++++++++++++++++++++++++
 docs/modeltranslation/usage.rst        |  6 ++++
 3 files changed, 53 insertions(+)

diff --git a/docs/modeltranslation/forms.rst b/docs/modeltranslation/forms.rst
index b9568a8..64f9224 100644
--- a/docs/modeltranslation/forms.rst
+++ b/docs/modeltranslation/forms.rst
@@ -19,6 +19,8 @@ Of course, upon saving, provided values would be set on proper attributes, depen
 current language.
 
 
+.. _formfield_nullability:
+
 Formfields and nullability
 --------------------------
 
diff --git a/docs/modeltranslation/registration.rst b/docs/modeltranslation/registration.rst
index 5450718..3dc5f80 100644
--- a/docs/modeltranslation/registration.rst
+++ b/docs/modeltranslation/registration.rst
@@ -55,6 +55,8 @@ translation will have been added some auto-magical fields. The next section
 explains how things are working under the hood.
 
 
+.. _TO_field_inheritance:
+
 ``TranslationOptions`` fields inheritance
 -----------------------------------------
 
@@ -161,6 +163,49 @@ can use the ``update_translation_fields`` command below. See
 :ref:`commands-update_translation_fields` for more info on this.
 
 
+``TranslationOptions`` attributes reference
+-------------------------------------------
+
+Quick cheatsheet with links to proper docs sections and examples showing expected syntax.
+
+Classes inheriting from ``TranslationOptions`` can have following attributes defined:
+
+.. attribute:: TranslationOptions.fields (required)
+
+    List of translatable model fields. See :ref:`registration`.
+
+    Some fields can be implicitly added through inheritance, see :ref:`TO_field_inheritance`.
+
+.. attribute:: TranslationOptions.fallback_languages
+
+    Control order of languages for fallback purposes. See :ref:`fallback_lang`. ::
+
+        fallback_languages = {'default': ('en', 'de', 'fr'), 'uk': ('ru',)}
+
+.. attribute:: TranslationOptions.fallback_values
+
+    Set the value that should be used if no fallback language yielded a value.
+    See :ref:`fallback_val`. ::
+
+        fallback_values = _('-- sorry, no translation provided --')
+        fallback_values = {'title': _('Object not translated'), 'text': '---'}
+
+.. attribute:: TranslationOptions.fallback_undefined
+
+    Set what value should be considered "no value". See :ref:`fallback_undef`. ::
+
+        fallback_undefined = None
+        fallback_undefined = {'title': 'no title', 'text': None}
+
+.. attribute:: TranslationOptions.empty_values
+
+    Override the value that should be saved in forms on empty fields.
+    See :ref:`formfield_nullability`. ::
+
+        empty_values = ''
+        empty_values = {'title': '', 'slug': None, 'desc': 'both'}
+
+
 .. _supported_field_matrix:
 
 Supported Fields Matrix
diff --git a/docs/modeltranslation/usage.rst b/docs/modeltranslation/usage.rst
index aee43b2..037c01a 100644
--- a/docs/modeltranslation/usage.rst
+++ b/docs/modeltranslation/usage.rst
@@ -226,6 +226,8 @@ title/content of the news than display empty strings. This is called *fallback*.
 
 There are several ways of controlling fallback, described below.
 
+.. _fallback_lang:
+
 Fallback languages
 ******************
 
@@ -275,6 +277,8 @@ Even more, all fallbacks may be switched on or off for just some exceptional blo
     with fallbacks(False):
         # Work with values for the active language only
 
+.. _fallback_val:
+
 Fallback values
 ***************
 
@@ -305,6 +309,8 @@ Fallback values can be also customized per model field::
 If current language and all fallback languages yield no field value, and no fallback values are
 defined, then modeltranslation will use field's default value.
 
+.. _fallback_undef:
+
 Fallback undefined
 ******************