[gnome-builder] doc: add search provider docs

[Christian Hergert <chergert src gnome org>]

commit 8b0cca1a4d3fb7860c3cbfa5c5e44e9a43a3eb11
Author: Christian Hergert <chergert redhat com>
Date:   Wed Sep 6 22:03:09 2017 -0700

    doc: add search provider docs

 doc/plugins/search.rst |   65 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 65 insertions(+), 0 deletions(-)
---
diff --git a/doc/plugins/search.rst b/doc/plugins/search.rst
index 5b592e8..10aac31 100644
--- a/doc/plugins/search.rst
+++ b/doc/plugins/search.rst
@@ -1,3 +1,68 @@
 ########################
 Extending Project Search
 ########################
+
+Builder provides a global search box in the top right of the workbench.
+It can be extended to provide new types of search results.
+
+For example, the ``file-search`` extension provides search results based on files found in the project tree.
+
+.. image:: ../figures/file-search.png
+   :width: 629 px
+   :align: center
+
+Additionally, the ``code-index`` extension provides search results based on an index built from your project 
code.
+
+.. image:: ../figures/symbol-search.png
+   :width: 605 px
+   :align: center
+
+To add new search results, implement the ``Ide.SearchProvider`` interface in your plugin.
+
+.. code-block:: python3
+
+   # my_plugin.py
+
+   import gi
+
+   from gi.repository import GObject
+   from gi.repository import Gio
+   from gi.repository import Ide
+
+   class MySearchResult(Ide.SearchResult):
+       def __index__(self, context, i)
+           self.context = context
+           self.title = 'Item ' + str(i)
+           self.score = i / 100.0
+
+       def do_get_source_location(self):
+           """
+           Currently, search results must point to a source location.
+
+           This may change in a future release to allow for more
+           flexability. Get in touch with us if you need this.
+           """
+           return Ide.SourceLocation.new(self.context, line, line_offset, 0)
+
+   class MySearchProvider(Ide.Object, Ide.SearchProvider):
+
+       def do_search_async(self, query, max_results, cancellable, callback, data):
+           """
+           Asynchronously searches for results.
+
+           The search engine will take the results from do_search_finish()
+           and add it to the search results list, sorted by score.
+           """
+           task = Gio.Task.new(self, cancellable, callback)
+           task.results = []
+
+           for i in range(0, 10):
+               result = MySearchResult(self.get_context(), i)
+               task.results.append(result)
+
+           task.return_boolean(True)
+
+       def do_search_finish(self, task):
+           return task.results
+
+