[gnome-builder] doc: add section on extending menus

[Christian Hergert <chergert src gnome org>]

commit 47ef27cf80591e2db3376e6e4e8823b047823a7f
Author: Christian Hergert <chergert redhat com>
Date:   Wed Sep 6 22:28:18 2017 -0700

    doc: add section on extending menus

 doc/plugins/menus.rst |   59 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 59 insertions(+), 0 deletions(-)
---
diff --git a/doc/plugins/menus.rst b/doc/plugins/menus.rst
index 9487a51..fa1f332 100644
--- a/doc/plugins/menus.rst
+++ b/doc/plugins/menus.rst
@@ -2,4 +2,63 @@
 Extending Application Menus
 ###########################
 
+Menus in Builder are implemented using the ``GtkBuilder`` based menu definitions.
+These are created in ``gtk/menus.ui`` files within your extensions resources.
+
+Menus are automatically merged into the application when your plugin is loaded.
+If the plugin is unloaded by the user, they will be automatically unloaded as well.
+
+Extended Menu Features
+======================
+
+The ``GMenu`` abstraction is somewhat limited in features that Builder requires.
+In particular, Builder needs advanced sorting, icons, and accelerators for menu items.
+To overcome this, Builder has special "menu merging" code which has been extrated into ``libdazzle`` (a 
utility library).
+
+Here is an example of how the valgrind plugin extends the Run menu.
+
+.. code-block:: xml
+   :caption: Embed file as a resource matching /org/gnome/Builder/plugins/valgrind_plugin/gtk/menus.ui
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <interface>
+     <!-- "run-menu" is the unique name of the run menu -->
+     <menu id="run-menu">
+       <!-- The menu has sections in it, just like GMenu -->
+       <section id="run-menu-section">
+         <item>
+           <!-- by specifying an id, we can position other items relatively -->
+           <attribute name="id">valgrind-run-handler</attribute>
+
+           <!-- after/before can be used to position this menu relative to others -->
+           <attribute name="after">default-run-handler</attribute>
+
+           <!-- the GAction name and action target to activate -->
+           <attribute name="action">run-manager.run-with-handler</attribute>
+           <attribute name="target">valgrind</attribute>
+
+           <!-- The label to display -->
+           <attribute name="label" translatable="yes">Run with Valgrind</attribute>
+
+           <!-- An "icon-name" to show if icons are to be visible in the menu -->
+           <attribute name="verb-icon-name">system-run-symbolic</attribute>
+
+           <!-- An accelerator to display if accelerators are to be displayed -->
+           <attribute name="accel">&lt;Control&gt;F10</attribute>
+         </item>
+       </section>
+     </menu>
+   </interface>
+
+For more information on embedding resources with Python-based plugins,
+see :ref:`creating embedded GResources<embedding_resources>`.
+
+Accessing Merged Menus
+======================
+
+Merged menus are available via the ``Dzl.Application`` base class of ``Ide.Application``.
+
+.. code-block:: python3
+
+   menu = Ide.Application.get_default().get_menu_by_id('run-menu')