[gnome-builder] doc: progress on workbench documentation

[Christian Hergert <chergert src gnome org>]

commit 134abddbe2d806755f2580d3139dc3baf4b295f8
Author: Christian Hergert <chergert redhat com>
Date:   Wed Mar 8 01:06:14 2017 -0800

    doc: progress on workbench documentation

 doc/plugins/headerbar.rst              |    3 --
 doc/plugins/index.rst                  |    7 ++++-
 doc/plugins/workbench.rst              |    3 --
 doc/plugins/workbench/actions.rst      |   34 +++++++++++++++++++++++++++
 doc/plugins/workbench/basics.rst       |   39 ++++++++++++++++++++++++++++++++
 doc/plugins/workbench/headerbar.rst    |   32 ++++++++++++++++++++++++++
 doc/plugins/workbench/index.rst        |   15 ++++++++++++
 doc/plugins/workbench/panels.rst       |   20 ++++++++++++++++
 doc/plugins/workbench/perspectives.rst |   21 +++++++++++++++++
 doc/plugins/workbench/widgets.rst      |   21 +++++++++++++++++
 10 files changed, 187 insertions(+), 8 deletions(-)
---
diff --git a/doc/plugins/index.rst b/doc/plugins/index.rst
index 295cf56..ad7c84d 100644
--- a/doc/plugins/index.rst
+++ b/doc/plugins/index.rst
@@ -2,13 +2,16 @@
 Creating Plugins
 ################
 
+The following provides examples of various ways you can extend Builder.
+All examples are provided in the Python 3 language for succinctness.
+You can also implement plugins in C or Vala.
+
 .. toctree::
    :maxdepth: 3
    :titlesonly:
 
    creating
-   workbench
-   headerbar
+   workbench/index
    greeter
    editor/index
    symbols/index
diff --git a/doc/plugins/workbench/actions.rst b/doc/plugins/workbench/actions.rst
new file mode 100644
index 0000000..4be4018
--- /dev/null
+++ b/doc/plugins/workbench/actions.rst
@@ -0,0 +1,34 @@
+Registering Workbench Actions
+=============================
+
+Using ``Gio.Action`` is a convenient way to attach actions to the workbench that contain state.
+For example, maybe for use by a button that should be insensitive when it cannot be used.
+Additionally, actions registered on the workbench can be activated using the command bar plugin.
+
+.. code-block:: python3
+   :caption: Registering an action on the workbench
+
+   import gi
+
+   from gi.repository import GObject
+   from gi.repository import Gio
+   from gi.repository import Ide
+
+   class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
+
+       def do_load(self, workbench):
+           action = Gio.SimpleAction.new('hello', None)
+           action.connect('activate', self.hello_activate)
+           workbench.add_action(action)
+
+       def do_unload(self, workbench):
+           workbench.remove_action('hello')
+
+       def hello_activate(self, action, param):
+           print('Hello activated!')
+
+This adds a new action named ``hello`` to the workbench.
+It can be connected to widgets by using the ``win.hello`` action-name.
+Additionally, you can call the action with ``hello`` from the command bar.
+
+To toggle whether or not the action can be activated. set the ``Gio.SimpleAction:enabled`` property.
diff --git a/doc/plugins/workbench/basics.rst b/doc/plugins/workbench/basics.rst
new file mode 100644
index 0000000..c20d145
--- /dev/null
+++ b/doc/plugins/workbench/basics.rst
@@ -0,0 +1,39 @@
+The Basics
+==========
+
+The basic mechanics of extending the workbench requires first creating an ``Ide.WorkbenchAddin``.
+Your subclass will created for each instance of the ``Ide.Workbench``.
+This conveniently allows you to track the state needed for your plugin for each workbench.
+
+.. code-block:: python3
+   :caption: A Basic WorkbenchAddin to demonstrate scaffolding
+   :name: basic-workbench-addin-py
+
+   import gi
+
+   from gi.repository import GObject
+   from gi.repository import Ide
+
+   class BasicWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
+
+       def do_load(self, workbench: Ide.Workbench):
+           pass
+
+       def do_unload(self, workbench: Ide.Workbench):
+           pass
+
+You will notice that at the top we import the packages we'll be using.
+Here we use the ``GObject`` and ``Ide`` packages from GObject Introspection.
+
+We then create a class which inherits from ``GObject.Object`` and implements the ``Ide.WorkbenchAddin`` 
interface.
+The ``Ide.WorkbenchAddin`` interface has two virtual methods to override, ``Ide.WorkbenchAddin.load()`` and 
``Ide.WorkbenchAddin.unload()``.
+
+.. note:: PyGObject uses ``do_`` prefix to indicate we are overriding a virtual method.
+
+The ``load`` virtual method is called to allow the plugin to initialize itself.
+This method is called when the workbench is setup or your plugin is loaded.
+
+When the ``unload`` virtual method is called the plugin should clean up after itself to leave Builder and 
the workbench in a consistent state.
+This method is called when the workbench is destroyed or your plugin is unloaded.
+
+
diff --git a/doc/plugins/workbench/headerbar.rst b/doc/plugins/workbench/headerbar.rst
new file mode 100644
index 0000000..94e34ca
--- /dev/null
+++ b/doc/plugins/workbench/headerbar.rst
@@ -0,0 +1,32 @@
+Adding Widgets to the Header Bar
+================================
+
+You might want to add a button to the workbench header bar.
+To do this, use an ``Ide.WorkbenchAddin`` and fetch the header bar using ``Ide.Workbench.get_headerbar()``.
+You can attach your widget to either the left or the right side of the ``Ide.OmniBar`` in the center of the 
header bar.
+Additionally, by specifying a ``Gtk.PackType``, you can align the button within the left or right of the 
header bar.
+
+We suggest using ``Gio.SimpleAction`` to attach an action to the workbench and then activating the action 
using the ``Gtk.Button:action-name`` property.
+
+.. code-block:: python3
+   :caption: Adding a button to the workbench header bar
+
+   import gi
+
+   from gi.repository import GObject
+   from gi.repository import Ide
+
+   class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
+
+       def do_load(self, workbench):
+           headerbar = workbench.get_headerbar()
+
+           # Add button to top-center-left
+           self.button = Gtk.Button(label='Click', action_name='win.hello', visible=True)
+           headerbar.insert_left(self.button, Gtk.PackType.PACK_END, 0)
+
+       def do_unload(self, workbench):
+           # remove the button we added
+           self.button.destroy()
+           self.button = None
+
diff --git a/doc/plugins/workbench/index.rst b/doc/plugins/workbench/index.rst
new file mode 100644
index 0000000..ab83098
--- /dev/null
+++ b/doc/plugins/workbench/index.rst
@@ -0,0 +1,15 @@
+#######################
+Extending the Workbench
+#######################
+
+.. toctree::
+   :maxdepth: 3
+   :titlesonly:
+
+   basics
+   actions
+   headerbar
+   widgets
+   perspectives
+   panels
+
diff --git a/doc/plugins/workbench/panels.rst b/doc/plugins/workbench/panels.rst
new file mode 100644
index 0000000..61dac73
--- /dev/null
+++ b/doc/plugins/workbench/panels.rst
@@ -0,0 +1,20 @@
+Registering Panels
+==================
+
+
+.. code-block:: python3
+
+   # my_plugin.py
+
+   import gi
+
+   from gi.repository import GObject
+   from gi.repository import Ide
+
+   class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
+
+       def do_load(self, workbench):
+           pass
+
+       def do_unload(self, workbench):
+           pass
diff --git a/doc/plugins/workbench/perspectives.rst b/doc/plugins/workbench/perspectives.rst
new file mode 100644
index 0000000..7c6ae4f
--- /dev/null
+++ b/doc/plugins/workbench/perspectives.rst
@@ -0,0 +1,21 @@
+Registering Perspectives
+========================
+
+
+.. code-block:: python3
+
+   # my_plugin.py
+
+   import gi
+
+   from gi.repository import GObject
+   from gi.repository import Ide
+
+   class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
+
+       def do_load(self, workbench):
+           pass
+
+       def do_unload(self, workbench):
+           pass
+
diff --git a/doc/plugins/workbench/widgets.rst b/doc/plugins/workbench/widgets.rst
new file mode 100644
index 0000000..153e194
--- /dev/null
+++ b/doc/plugins/workbench/widgets.rst
@@ -0,0 +1,21 @@
+Adding Widgets to the Workbench
+===============================
+
+
+.. code-block:: python3
+
+   # my_plugin.py
+
+   import gi
+
+   from gi.repository import GObject
+   from gi.repository import Ide
+
+   class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
+
+       def do_load(self, workbench):
+           pass
+
+       def do_unload(self, workbench):
+           pass
+