Add OpenSearch capability.

CHANGES

@@ -64,8 +64,11 @@ New features added
     the default templates.
   - Templates now have an XHTML doctype, to be consistent with docutils'
     HTML output.
+  - You can now create an OpenSearch description file with the
+    ``html_use_opensearch`` config value.
 
-Thanks to Jacob Kaplan-Moss, Talin and Sebastian Wiesner for suggestions.
+Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and
+Sebastian Wiesner for suggestions.
 
 Bugs fixed
 ----------

TODO

@@ -9,7 +9,6 @@ Sphinx
 - option for compact module index
 - HTML section numbers?
 - split the general index?
-- add OpenSearch
 - "seealso" links to external examples, see http://svn.python.org/projects/sandbox/trunk/seealso/ and http://effbot.org/zone/idea-seealso.htm
 - "often used" combo box in sidebar
 - source file cross-references?

doc/config.rst

@@ -227,7 +227,13 @@ that use Sphinx' HTMLWriter class.
 .. confval:: html_copy_source
 
    If true, the reST sources are included in the HTML build as
-   :file:`_sources/{name}`.
+   :file:`_sources/{name}`.  The default is ``True``.
+
+.. confval:: html_use_opensearch
+
+   If true, an `OpenSearch <http://opensearch.org>` description file will be
+   output, and all pages will contain a ``<link>`` tag referring to it.
+   The default is ``False``.
 
 .. confval:: html_translator_class
 

sphinx/builder.py

@@ -330,6 +330,7 @@ class StandaloneHTMLBuilder(Builder):
             copyright = self.config.copyright,
             style = self.config.html_style,
             use_modindex = self.config.html_use_modindex,
+            use_opensearch = self.config.html_use_opensearch,
             builder = self.name,
             parents = [],
             titles = {},
@@ -468,6 +469,11 @@ class StandaloneHTMLBuilder(Builder):
             self.info(' '+pagename, nonl=1)
             self.handle_page(pagename, {}, template)
 
+        if self.config.html_use_opensearch:
+            self.info(' opensearch', nonl=1)
+            fn = path.join(self.outdir, '_static', 'opensearch.xml')
+            self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn)
+
         self.info()
 
         # copy image files
@@ -544,7 +550,8 @@ class StandaloneHTMLBuilder(Builder):
     def get_target_uri(self, docname, typ=None):
         return docname + '.html'
 
-    def handle_page(self, pagename, addctx, templatename='page.html'):
+    def handle_page(self, pagename, addctx, templatename='page.html',
+                    outfilename=None):
         ctx = self.globalcontext.copy()
         ctx['current_page_name'] = pagename
 
@@ -561,6 +568,7 @@ class StandaloneHTMLBuilder(Builder):
         ctx.update(addctx)
 
         output = self.templates.render(templatename, ctx)
+        if not outfilename:
             outfilename = path.join(self.outdir, os_path(pagename) + '.html')
         ensuredir(path.dirname(outfilename)) # normally different from self.outdir
         try:
@@ -606,11 +614,13 @@ class PickleHTMLBuilder(StandaloneHTMLBuilder):
             return docname[:-5] # up to sep
         return docname + SEP
 
-    def handle_page(self, pagename, ctx, templatename='page.html'):
+    def handle_page(self, pagename, ctx, templatename='page.html',
+                    outfilename=None):
         ctx['current_page_name'] = pagename
         sidebarfile = self.config.html_sidebars.get(pagename, '')
         if sidebarfile:
             ctx['customsidebar'] = path.join(self.srcdir, sidebarfile)
+        if not outfilename:
             outfilename = path.join(self.outdir, os_path(pagename) + '.fpickle')
         ensuredir(path.dirname(outfilename))
         f = open(outfilename, 'wb')

sphinx/config.py

@@ -55,6 +55,7 @@ class Config(object):
         html_additional_pages = ({}, False),
         html_use_modindex = (True, False),
         html_copy_source = (True, False),
+        html_use_opensearch = (False, False),
 
         # HTML help options
         htmlhelp_basename = ('pydoc', False),

sphinx/quickstart.py

@@ -126,6 +126,10 @@ html_last_updated_fmt = '%%b %%d, %%Y'
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 #html_copy_source = True
 
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.
+#html_use_opensearch = False
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%(project)sdoc'
 

sphinx/templates/layout.html

@@ -62,6 +62,11 @@
     <script type="text/javascript" src="{{ pathto('_static/interface.js', 1) }}"></script>
     <script type="text/javascript" src="{{ pathto('_static/doctools.js', 1) }}"></script>
     {%- endif %}
+    {%- if use_opensearch %}
+    <link rel="search" type="application/opensearchdescription+xml"
+          title="Search within {{ docstitle }}"
+          href="{{ pathto('_static/opensearch.xml', 1) }}"/>
+    {%- endif %}
 {%- block rellinks %}
     {%- if hasdoc('about') %}
     <link rel="author" title="About these documents" href="{{ pathto('about') }}" />

sphinx/templates/opensearch.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
+  <ShortName>{{ project }}</ShortName>
+  <LongName>{{ docstitle }}</LongName>
+  <Description>Search {{ docstitle }}</Description>
+  <InputEncoding>utf-8</InputEncoding>
+  <Url type="text/html" method="get" template="{{ pathto('search') }}?">
+    <Param name="q" value="{searchTerms}" />
+    <Param name="check_keywords" value="yes" />
+    <Param name="area" value="default" />
+  </Url>
+{% block extra %}{# Put e.g. an <Image> element here. #}{% endblock %}
+</OpenSearchDescription>