[gnome-builder] doc: move completion docs around

[Christian Hergert <chergert src gnome org>]

commit faa48eaf829d8793c8c906c96901c388bb4388f7
Author: Christian Hergert <chergert redhat com>
Date:   Wed Jun 20 18:45:16 2018 -0700

    doc: move completion docs around

 doc/help/plugins/autocompletion.rst        | 123 -----------------------
 doc/help/plugins/editor/autocompletion.rst | 151 ++++++++++++++++++++++++++++-
 doc/help/plugins/index.rst                 |   1 -
 3 files changed, 148 insertions(+), 127 deletions(-)
---
diff --git a/doc/help/plugins/editor/autocompletion.rst b/doc/help/plugins/editor/autocompletion.rst
index 87c7dd525..25864706a 100644
--- a/doc/help/plugins/editor/autocompletion.rst
+++ b/doc/help/plugins/editor/autocompletion.rst
@@ -1,3 +1,148 @@
-##############
-Autocompletion
-##############
+##############################
+Providing Completion Proposals
+##############################
+
+Builder has a robust completion engine that allows for efficent access to results.
+Plugins should implement the ``Ide.CompletionProvider`` interface to provide a ``Gio.ListModel`` of 
``Ide.CompletionProposal``.
+Plugins have an opportunity to refine results as the user continues to provide input.
+
+.. note:: You can learn more about the implementation at 
https://blogs.gnome.org/chergert/2018/06/09/a-new-completion-engine-for-builder/
+
+
+Example Completion Provider
+===========================
+
+.. code-block:: python3
+
+   # my_plugin.py
+
+   import gi
+
+   from gi.repository import GObject
+   from gi.repository import Gio
+   from gi.repository import Ide
+
+   class MyCompletionProvider(GLib.Object, Ide.CompletionProvider):
+
+       def do_populate_async(self, context, cancellable, callback, data):
+           """
+           @context: an Ide.CompletionContext containing state for the completion request
+           @cancellable: a Gio.Cancellable that can be used to cancel the request
+           @callback: a callback to execute after proposals are generated
+           @data: closure data (unnecessary for us since PyGObject handles it)
+           """
+
+           # Create a task for our async operation
+           task = Ide.Task.new(self, cancellable, callback)
+
+           # Create a container for all our results. You may consider implementing
+           # Gio.ListModel directly if performance is of high concern.
+           task.proposals = Gio.ListStore(type(Ide.CompletionProposal))
+
+           item = MyProposal('my proposal')
+           task.proposals.append(item)
+
+           # Complete the task so that the completion engine calls us back at
+           # do_populate_finish() to complete the operation.
+           task.return_boolean(True)
+
+
+       def do_populate_finish(self, task):
+           """
+           @task: the task we created in do_populate_async()
+
+           The goal here is to copmlete the operation by returning our Gio.ListModel
+           back to the caller.
+           """
+           if task.propagate_boolean():
+               return task.proposals
+
+
+       def do_display_proposal(self, row, context, typed_text, proposal):
+           """
+           We need to update the state of @row using the info from our proposal.
+           This is called as the user moves through the result set.
+
+           @row: the Ide.CompletionListBoxRow to display
+           @context: the Ide.CompletionContext
+           @typed_text: what the user typed
+           @proposal: the proposal to display using @row
+           """
+           row.set_icon_name()
+           row.set_left('Left hand side')
+           row.set_right('Right hand side')
+           row.set_center(proposal.title)
+
+           # You might find fuzzy highlighting useful for creating Pango markup
+           markup = Ide.Completion.fuzzy_highlight(proposal.title, typed_text)
+
+           # If you have Pango markup, you can use set_center_markup()
+           row.set_center_markup(markup)
+
+
+       def do_activate_proposal(self, context, proposal, key):
+           """
+           @proposal: the proposal to be activated
+           @key: the Gdk.EventKey representing what the user pressed to activate the row
+                 you may want to use this to alter what is inserted (such as converting
+                 . to -> in a C/C++ language provider).
+
+           This is where we do the work to insert the proposal. You may want to
+           check out the snippet engine to use snippets instead, as some of the
+           providers do which auto-complete parameters.
+           """
+
+           buffer = context.get_buffer()
+
+           # Start a "user action" so that all the changes are coalesced into a
+           # single undo action.
+           buffer.begin_user_action()
+
+           # Delete the typed text if any
+           has_selection, begin, end = context.get_bounds()
+           if has_selection:
+               buffer.delete(begin, end)
+
+           # Now insert our proposal
+           buffer.insert(begin, proposal.title, len(proposal.title))
+
+           # Complete the user action
+           buffer.begin_end_action()
+
+
+       def do_refilter(self, context, proposals):
+           """
+           If you can refilter the results based on updated typed text, this
+           is where you would adjust @proposals to do that. @proposals is the
+           Gio.ListModel returned from do_populate_finish().
+           """
+           typed_text = context.get_word()
+           # filter results...
+           return True
+
+
+   class MyProposal(GObject.Object, Ide.CompletionProposal):
+       def __init__(self, title):
+           super().__init__()
+           self.title = title
+
+
+There are a number of additional things you can implement in your provider.
+See the IdeCompletionProvider implementation for a description of the interface.
+
+
+Examples from Builder
+=====================
+
+ * `Includes completion provider`_ for header includes in C/C++ files
+ * `Jedi completion provider`_ for Python completions
+ * `Ctags completion provider`_ for lightning-fast ctags completion
+ * `Clang completion provider`_ for a fast, caching, completion provider based on libclang
+ * `Vala completion provider`_ for completions in the Vala language
+
+
+.. _`Includes completion provider`: 
https://gitlab.gnome.org/GNOME/gnome-builder/blob/master/src/plugins/c-pack/cpack-completion-provider.c
+.. _`Jedi completion provider`: 
https://gitlab.gnome.org/GNOME/gnome-builder/blob/master/src/plugins/jedi/jedi_plugin.py
+.. _`Ctags completion provider`: 
https://gitlab.gnome.org/GNOME/gnome-builder/blob/master/src/plugins/ctags/ide-ctags-completion-provider.c
+.. _`Clang completion provider`: 
https://gitlab.gnome.org/GNOME/gnome-builder/blob/master/src/plugins/clang/ide-clang-completion-provider.c
+.. _`Vala completion provider`: 
https://gitlab.gnome.org/GNOME/gnome-builder/blob/master/src/plugins/vala-pack/ide-vala-completion-provider.vala
diff --git a/doc/help/plugins/index.rst b/doc/help/plugins/index.rst
index 3588e5694..aa37f43ab 100644
--- a/doc/help/plugins/index.rst
+++ b/doc/help/plugins/index.rst
@@ -21,7 +21,6 @@ You may also chooser to implement extensions in C or Vala.
    symbols/index
    building/index
    processes/index
-   autocompletion
    devices
    running
    keybindings