[gnome-builder] doc: add example for preferences

[Christian Hergert <chergert src gnome org>]

commit 4141d3963c87699cfa83a9ac80745366596c9945
Author: Christian Hergert <chergert redhat com>
Date:   Wed Sep 6 23:08:22 2017 -0700

    doc: add example for preferences

 doc/plugins/preferences.rst |   72 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 72 insertions(+), 0 deletions(-)
---
diff --git a/doc/plugins/preferences.rst b/doc/plugins/preferences.rst
index 27b79bc..06cb566 100644
--- a/doc/plugins/preferences.rst
+++ b/doc/plugins/preferences.rst
@@ -1,3 +1,75 @@
 ###################################
 Registering Application Preferences
 ###################################
+
+Builder's preferences are designed in such a way that the core application preferences and extension 
preferences feel cohesive.
+This is often not the case with "plugin-based" applications.
+
+To do this, we created the ``Ide.Preferences`` interface.
+Extensions can implement the ``Ide.PreferencesAddin`` interface and register preferences with the 
``Ide.Preferences`` instance.
+This allows the preferences to be seamlessly merged together based on the desired page, group, and 
preference type.
+They are even searchable!
+
+
+.. code-block:: python3
+
+   # my_plugin.py
+
+   import gi
+
+   from gi.repository import GObject
+   from gi.repository import Ide
+
+   _ = Ide.gettext
+
+   class MyPreferencesAddin(GObject.Object, Ide.PreferencesAddin):
+
+       def do_load(self, prefs):
+
+           # add a new switch row
+           self.completion_id = prefs.add_switch(
+                   # to the code-insight page
+                   'code-insight',
+
+                   # in the completion group
+                   'completion',
+
+                   # mapping to the gsettings schema
+                   'org.gnome.builder.extension-type',
+
+                   # with the gsettings schema key
+                   'enabled',
+
+                   # And the gsettings path
+                   '/',
+
+                   # The target GVariant value if necessary (usually not)
+                   None,
+
+                   # title
+                   _("Suggest Python completions"),
+
+                   # subtitle
+                   _("Use Jedi to provide completions for the Python language"),
+
+                   # keywords
+                   _("jedi python search autocompletion API"),
+                   
+                   # with sort priority
+                   30)
+
+           # there are plenty of other types of things you can add.
+           # see dzl-preferences.h for an example of the API you can call
+           # such as:
+           #
+           #  - add_group()
+           #  - add_list_group()
+           #  - add_font_button()
+           #  - add_radio()
+           #  - add_spin_button()
+           #  - add_file_chooser()
+           #  - add_custom() (custom widgets)
+
+       def do_unload(self, prefs):
+           prefs.remove_id(self.completion_id)
+