updated documentation

doc/web/api.rst

@@ -13,6 +13,10 @@ Web Support API
 
    Initialize attributes.
 
+.. method:: build()
+
+   Build the data used by the web support package.
+
 .. method:: get_document(docname)
 
    Retrieve the context dictionary corresponding to the *docname*.

doc/web/quickstart.rst

@@ -3,6 +3,9 @@
 Web Support Quick Start
 =======================
 
+Getting Started
+~~~~~~~~~~~~~~~
+
 To use the :ref:`websupportapi` in your application you must import
 the :class:`~sphinx.websupport.api.WebSupport` object::
 
@@ -13,22 +16,48 @@ object. You will then need to provide some information about your
 environment::
 
     support.init(srcdir='/path/to/rst/sources/',
-                 outdir='/path/to/build/outdir')
+                 outdir='/path/to/build/outdir',
+		 search='xapian')
 
-You only need to provide a srcdir if you are building documentation::
+Note: You only need to provide a srcdir if you are building documentation.
+
+Building Documentation Data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to use the web support package in a webapp, you will need to
+build the data it uses. This data includes document data used to display
+documentation and search indexes. To build this data, call the build method::
 
     support.build()
 
 This will create the data the web support package needs and place
-it in *outdir*. You can then access this data by calling the 
+it in *outdir*. 
-get_document(docname) method. For example, to retrieve the "contents" 
+
-document, do this::
+Accessing Document Data
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To access document data, call the get_document(docname) method. For example, 
+to retrieve the "contents" document, do this::
 
     contents_doc = support.get_document('contents')
 
 This will return a dictionary containing the context you need to render
 a document.
 
+Performing Searches
+~~~~~~~~~~~~~~~~~~~
+
+To perform a search, call the get_search_results(q) method, with *q* being
+the string to be searched for::
+
+    q = request.GET['q']
+    search_doc = support.get_search_results(q)
+
+This will return a dictionary in the same format as get_document() returns.
+
+Full Example
+~~~~~~~~~~~~
+
 A more useful example, in the form of a `Flask <http://flask.pocoo.org/>`_
 application is::
 
@@ -44,6 +73,11 @@ application is::
         document = support.get_document(docname)
         return render_template('doc.html', document=document)
 
+    @app.route('/docs/search')
+    def search():
+        document = support.get_search_results(request.args.get('q', ''))
+	return render_template('doc.html', document=document)
+
 In the previous example the doc.html template would look something 
 like this::
 
@@ -69,9 +103,18 @@ like this::
       </script>
     {% endblock %}
 
+    {% block relbar %}
+      {{ document.relbar|safe }}
+    {% endblock %}
+
     {% block body %}
       {{ document.body|safe }}
     {% endblock %}
 
     {% block sidebar %}
+      {{ document.sidebar|safe }}
     {% endblock %}
+
+    {% block relbar %}
+      {{ document.relbar|safe }}
+    {% endblock %}