[gnome-builder] doc: add panel example

[Christian Hergert <chergert src gnome org>]

commit b10f6dc0461bfc9b185c2c2079e1880c200de5e0
Author: Christian Hergert <chergert redhat com>
Date:   Wed Sep 6 14:45:54 2017 -0700

    doc: add panel example

 doc/plugins/workbench/panels.rst |   50 ++++++++++++++++++++++++++++++++-----
 1 files changed, 43 insertions(+), 7 deletions(-)
---
diff --git a/doc/plugins/workbench/panels.rst b/doc/plugins/workbench/panels.rst
index 61dac73..60c087a 100644
--- a/doc/plugins/workbench/panels.rst
+++ b/doc/plugins/workbench/panels.rst
@@ -1,6 +1,18 @@
-Registering Panels
-==================
+Adding Panels to the Workbench
+==============================
 
+You may want to write an extension that adds a panel which displays information to the user.
+Builder provides API for this via the "Editor Perspective".
+
+At a high level, the design of the editor is broken into four parts.
+
+ - The code editors in the center of the perspective
+ - The left panel, which contains the "sources" of actions
+ - The bottom panel, which contains utilities
+ - The right panel, which is transient and contextual to the operation at hand
+
+The easiest way to add a panel is to register an ``Ide.EditorAddin`` which adds the panels in the 
``do_load()`` function.
+You'll be provided access to the editor perspective with the ``editor`` variable.
 
 .. code-block:: python3
 
@@ -10,11 +22,35 @@ Registering Panels
 
    from gi.repository import GObject
    from gi.repository import Ide
+   from gi.repository import Dazzle
+
+   class MyEditorAddin(GObject.Object, Ide.EditorAddin):
+
+       def do_load(self, editor):
+
+           # Add a widget to the left panel (aka Sidebar)
+           self.panel = Gtk.Label(visible=True, label='My Left Panel')
+           left_panel = editor.get_sidebar()
+           left_panel.add_section('my-section',
+                                  'My Section Title',
+                                  'my-section-icon-name',
+                                  None, # Menu id if necessary
+                                  None, # Menu icon name if necessary
+                                  self.panel,
+                                  100)  # Sort priority
+
+           # To add a utility section
+           self.bottom = Dazzle.DockWidget(title='My Bottom Panel', icon_name='gtk-missing', visible=True)
+           self.bottom.add(Gtk.Label(lable='Hello, Bottom Panel', visible=True))
+           editor.get_utilties().add(self.bottom)
+
+       def do_unload(self, editor):
+
+           # Remove our widgets
+           self.panel.destroy()
+           self.bottom.destroy()
 
-   class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
+           self.bottom = None
+           self.panel = None
 
-       def do_load(self, workbench):
-           pass
 
-       def do_unload(self, workbench):
-           pass