[gnome-builder] help: update various workspace docs

[Christian Hergert <chergert src gnome org>]

commit ea38b390f8ec677643e3198bad748399d925cc51
Author: Christian Hergert <chergert redhat com>
Date:   Tue Mar 12 16:04:50 2019 -0700

    help: update various workspace docs

 doc/help/plugins/workbench/headerbar.rst    | 23 +++++++++++---
 doc/help/plugins/workbench/index.rst        |  2 +-
 doc/help/plugins/workbench/panels.rst       | 17 +++++-----
 doc/help/plugins/workbench/perspectives.rst | 48 -----------------------------
 doc/help/plugins/workbench/surfaces.rst     | 40 ++++++++++++++++++++++++
 5 files changed, 67 insertions(+), 63 deletions(-)
---
diff --git a/doc/help/plugins/workbench/headerbar.rst b/doc/help/plugins/workbench/headerbar.rst
index 1d355fcc6..181821db2 100644
--- a/doc/help/plugins/workbench/headerbar.rst
+++ b/doc/help/plugins/workbench/headerbar.rst
@@ -1,5 +1,5 @@
-Adding Widgets to the Header Bar
-================================
+Extend HeaderBar and OmniBar
+============================
 
 You might want to add a button to the workspace header bar.
 To do this, use an ``Ide.WorkspaceAddin`` and fetch the header bar using ``Ide.Workspace.get_headerbar()``.
@@ -15,8 +15,11 @@ We suggest using ``Gio.SimpleAction`` to attach an action to the workspace and t
    from gi.repository import GObject, Ide
 
    class MyWorkspaceAddin(GObject.Object, Ide.WorkspaceAddin):
+       """
+       Add a new button to the header bar.
+       """
 
-       def do_load(self, workspace):
+       def do_load(self, workspace: Ide.Workspace):
            headerbar = workspace.get_headerbar()
 
            # Add button to top-center-left
@@ -31,8 +34,20 @@ We suggest using ``Gio.SimpleAction`` to attach an action to the workspace and t
            self.button = Gtk.Button(label='Click', action_name='win.hello', visible=True)
            headerbar.add_secondary(self.button)
 
-       def do_unload(self, workspace):
+       def do_unload(self, workspace: Ide.Workspace):
            # remove the button we added
            self.button.destroy()
            self.button = None
 
+   class MyOmniBarAddin(GObject.Object, Ide.OmniBarAddin):
+       """
+       Extend the omnibar by adding a button inside the bar.
+       """
+
+       def do_load(self, omni_bar: Ide.OmniBar):
+           self.button = Gtk.Button(visible=True, label='Hi')
+           omni_bar.add_status_icon(self.button, 0)
+
+       def do_unload(self, omni_bar: Ide.OmniBar):
+           self.button.destroy()
+           self.button = None
diff --git a/doc/help/plugins/workbench/index.rst b/doc/help/plugins/workbench/index.rst
index 3ea91dbd7..71fb6755f 100644
--- a/doc/help/plugins/workbench/index.rst
+++ b/doc/help/plugins/workbench/index.rst
@@ -9,6 +9,6 @@ Extending the Workbench
    basics
    actions
    headerbar
-   perspectives
+   surfaces
    panels
 
diff --git a/doc/help/plugins/workbench/panels.rst b/doc/help/plugins/workbench/panels.rst
index 664ef2c6d..8054a42db 100644
--- a/doc/help/plugins/workbench/panels.rst
+++ b/doc/help/plugins/workbench/panels.rst
@@ -1,18 +1,18 @@
-Adding Panels to the Workbench
+Adding Panels to the Workspace
 ==============================
 
 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".
+Builder provides API for this via the "Editor Surface".
 
 At a high level, the design of the editor is broken into four parts.
 
- - The code editors in the center of the perspective
+ - The code editors in the center of the surface
  - 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.
+You'll be provided access to the editor surface with the ``editor`` variable.
 
 .. code-block:: python3
 
@@ -20,14 +20,11 @@ You'll be provided access to the editor perspective with the ``editor`` variable
 
    import gi
 
-   from gi.repository import GObject
-   from gi.repository import Ide
-   from gi.repository import Gtk
-   from gi.repository import Dazzle
+   from gi.repository import GObject, Gtk, Dazzle, Ide
 
    class MyEditorAddin(GObject.Object, Ide.EditorAddin):
 
-       def do_load(self, editor):
+       def do_load(self, editor: Ide.EditorSurface):
 
            # Add a widget to the left panel (aka Sidebar)
            self.panel = Gtk.Label(visible=True, label='My Left Panel')
@@ -45,7 +42,7 @@ You'll be provided access to the editor perspective with the ``editor`` variable
            self.bottom.add(Gtk.Label(lable='Hello, Bottom Panel', visible=True))
            editor.get_utilties().add(self.bottom)
 
-       def do_unload(self, editor):
+       def do_unload(self, editor: Ide.EditorSurface):
 
            # Remove our widgets
            self.panel.destroy()
diff --git a/doc/help/plugins/workbench/surfaces.rst b/doc/help/plugins/workbench/surfaces.rst
new file mode 100644
index 000000000..44d7b8c0f
--- /dev/null
+++ b/doc/help/plugins/workbench/surfaces.rst
@@ -0,0 +1,40 @@
+Adding a Surface
+================
+
+Everything in Builder below the header bar is implemented as a "Surface".
+For example, the editor is a surface and so is the "Build Preferences" interface.
+
+You may want to create a surface if you require the users full attention and other editor components may be 
distracting.
+
+.. note:: We generally suggest looking for alternatives to creating a surface as it can be cumbersome for 
the user to switch contexts.
+
+.. code-block:: python3
+
+   # my_plugin.py
+
+   import gi
+
+   from gi.repository import GObject, Gtk, Ide
+
+   class MySurface(Ide.Surface):
+       def __init__(self, *args, **kwargs):
+           super().__init__(*args, **kwargs)
+
+           self.add(Gtk.Label(label='My Surface', visible=True))
+
+           self.set_icon_name('gtk-missing')
+           self.set_title('My Surface')
+
+   class MyWorkspaceAddin(GObject.Object, Ide.WorkspaceAddin):
+       surface = None
+
+       def do_load(self, workspace: Ide.Workspace):
+           if type(workspace) == Ide.PrimaryWorkspace:
+               self.surface = MySurface(visible=True)
+               workspace.add_surface(self.surface)
+
+       def do_unload(self, workspace: Ide.Workspace):
+           if self.surface is not None:
+               self.surface.destroy()
+               self.surface = None
+