
Search Adapters
***************

To create a custom search adapter you will need to subclass the
"BaseSearch" class.  Then create an instance of the new class and pass
that as the *search* keyword argument when you create the "WebSupport"
object:

   support = WebSupport(srcdir=srcdir,
                        builddir=builddir,
                        search=MySearch())

For more information about creating a custom search adapter, please
see the documentation of the "BaseSearch" class below.

class class sphinx.websupport.search.BaseSearch

   Defines an interface for search adapters.


BaseSearch Methods
==================

   The following methods are defined in the BaseSearch class. Some
   methods do not need to be overridden, but some ("add_document()"
   and "handle_query()") must be overridden in your subclass. For a
   working example, look at the built-in adapter for whoosh.

BaseSearch.init_indexing(changed=[])

   Called by the builder to initialize the search indexer. *changed*
   is a list of pagenames that will be reindexed. You may want to
   remove these from the search index before indexing begins.

   Parameters:
      **changed** -- a list of pagenames that will be re-indexed

BaseSearch.finish_indexing()

   Called by the builder when writing has been completed. Use this to
   perform any finalization or cleanup actions after indexing is
   complete.

BaseSearch.feed(pagename, title, doctree)

   Called by the builder to add a doctree to the index. Converts the
   *doctree* to text and passes it to "add_document()". You probably
   won't want to override this unless you need access to the
   *doctree*. Override "add_document()" instead.

   Parameters:
      * **pagename** -- the name of the page to be indexed

      * **title** -- the title of the page to be indexed

      * **doctree** -- is the docutils doctree representation of the
        page

BaseSearch.add_document(pagename, title, text)

   Called by "feed()" to add a document to the search index. This
   method should should do everything necessary to add a single
   document to the search index.

   *pagename* is name of the page being indexed. It is the combination
   of the source files relative path and filename, minus the
   extension. For example, if the source file is "ext/builders.rst",
   the *pagename* would be "ext/builders". This will need to be
   returned with search results when processing a query.

   Parameters:
      * **pagename** -- the name of the page being indexed

      * **title** -- the page's title

      * **text** -- the full text of the page

BaseSearch.query(q)

   Called by the web support api to get search results. This method
   compiles the regular expression to be used when "extracting
   context", then calls "handle_query()".  You won't want to override
   this unless you don't want to use the included "extract_context()"
   method.  Override "handle_query()" instead.

   Parameters:
      **q** -- the search query string.

BaseSearch.handle_query(q)

   Called by "query()" to retrieve search results for a search query
   *q*. This should return an iterable containing tuples of the
   following format:

      (<path>, <title>, <context>)

   *path* and *title* are the same values that were passed to
   "add_document()", and *context* should be a short text snippet of
   the text surrounding the search query in the document.

   The "extract_context()" method is provided as a simple way to
   create the *context*.

   Parameters:
      **q** -- the search query

BaseSearch.extract_context(text, length=240)

   Extract the context for the search query from the document's full
   *text*.

   Parameters:
      * **text** -- the full text of the document to create the
        context for

      * **length** -- the length of the context snippet to return.
