[gnome-builder] doc: add example for perspectives

[Christian Hergert <chergert src gnome org>]

commit 11c8f3c4a03a23991f7f69c157800d411e635f2d
Author: Christian Hergert <chergert redhat com>
Date:   Wed Sep 6 14:56:43 2017 -0700

    doc: add example for perspectives

 doc/plugins/workbench/panels.rst       |    1 +
 doc/plugins/workbench/perspectives.rst |   31 +++++++++++++++++++++++++++++--
 2 files changed, 30 insertions(+), 2 deletions(-)
---
diff --git a/doc/plugins/workbench/panels.rst b/doc/plugins/workbench/panels.rst
index 60c087a..664ef2c 100644
--- a/doc/plugins/workbench/panels.rst
+++ b/doc/plugins/workbench/panels.rst
@@ -22,6 +22,7 @@ You'll be provided access to the editor perspective with the ``editor`` variable
 
    from gi.repository import GObject
    from gi.repository import Ide
+   from gi.repository import Gtk
    from gi.repository import Dazzle
 
    class MyEditorAddin(GObject.Object, Ide.EditorAddin):
diff --git a/doc/plugins/workbench/perspectives.rst b/doc/plugins/workbench/perspectives.rst
index 7c6ae4f..9157e00 100644
--- a/doc/plugins/workbench/perspectives.rst
+++ b/doc/plugins/workbench/perspectives.rst
@@ -1,6 +1,14 @@
 Registering Perspectives
 ========================
 
+Everything in Builder below the header bar is implemented as a "Perspective".
+For example, the editor is a perspective and so is the preferences interface.
+
+You may want to create a perspective if you require the users full attention
+and other editor components may be distracting.
+
+.. note:: We generally suggest looking for alternatives to creating a perspective as it
+          can be cumbersome for the user to switch contexts.
 
 .. code-block:: python3
 
@@ -10,12 +18,31 @@ Registering Perspectives
 
    from gi.repository import GObject
    from gi.repository import Ide
+   from gi.repository import Gtk
+
+   class MyPerspective(Gtk.Bin, Ide.Perspective):
+       def __init__(self, *args, **kwargs):
+           super().__init__(*args, **kwargs)
+
+           self.add(Gtk.Label(label='My Perspective', visible=True))
+
+       def do_get_icon_name(self):
+           return 'gtk-missing'
+
+       def do_get_title(self):
+           return 'My Perspective'
+
+       def do_get_accelerator(self):
+           return '<Control><Shift><Alt>Z'
 
    class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
+       perspective = None
 
        def do_load(self, workbench):
-           pass
+           self.perspective = MyPerspective(visible=True)
+           workbench.add_perspective(self.perspective)
 
        def do_unload(self, workbench):
-           pass
+           self.perspective.destroy()
+           self.perspective = None