[Python-checkins] r62532 - in doctools/trunk: CHANGES TODO doc/config.rst sphinx/builder.py sphinx/config.py sphinx/quickstart.py sphinx/templates/layout.html sphinx/templates/opensearch.xml

Sun Apr 27 20:08:55 CEST 2008

Author: georg.brandl
Date: Sun Apr 27 20:08:55 2008
New Revision: 62532
Log:
Add OpenSearch capability.
Added:
 doctools/trunk/sphinx/templates/opensearch.xml
Modified:
 doctools/trunk/CHANGES
 doctools/trunk/TODO
 doctools/trunk/doc/config.rst
 doctools/trunk/sphinx/builder.py
 doctools/trunk/sphinx/config.py
 doctools/trunk/sphinx/quickstart.py
 doctools/trunk/sphinx/templates/layout.html
Modified: doctools/trunk/CHANGES
==============================================================================

--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Sun Apr 27 20:08:55 2008
@@ -64,8 +64,11 @@
 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
 ----------
Modified: doctools/trunk/TODO
==============================================================================
--- doctools/trunk/TODO	(original)
+++ doctools/trunk/TODO	Sun Apr 27 20:08:55 2008
@@ -9,7 +9,6 @@
 - 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?
Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst	(original)
+++ doctools/trunk/doc/config.rst	Sun Apr 27 20:08:55 2008
@@ -227,7 +227,13 @@
 .. 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
 
Modified: doctools/trunk/sphinx/builder.py
==============================================================================
--- doctools/trunk/sphinx/builder.py	(original)
+++ doctools/trunk/sphinx/builder.py	Sun Apr 27 20:08:55 2008
@@ -330,6 +330,7 @@
 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 @@
 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 @@
 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,7 +568,8 @@
 ctx.update(addctx)
 
 output = self.templates.render(templatename, ctx)
- outfilename = path.join(self.outdir, os_path(pagename) + '.html')
+ if not outfilename:
+ outfilename = path.join(self.outdir, os_path(pagename) + '.html')
 ensuredir(path.dirname(outfilename)) # normally different from self.outdir
 try:
 f = codecs.open(outfilename, 'w', 'utf-8')
@@ -606,12 +614,14 @@
 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)
- outfilename = path.join(self.outdir, os_path(pagename) + '.fpickle')
+ if not outfilename:
+ outfilename = path.join(self.outdir, os_path(pagename) + '.fpickle')
 ensuredir(path.dirname(outfilename))
 f = open(outfilename, 'wb')
 try:
Modified: doctools/trunk/sphinx/config.py
==============================================================================
--- doctools/trunk/sphinx/config.py	(original)
+++ doctools/trunk/sphinx/config.py	Sun Apr 27 20:08:55 2008
@@ -55,6 +55,7 @@
 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),
Modified: doctools/trunk/sphinx/quickstart.py
==============================================================================
--- doctools/trunk/sphinx/quickstart.py	(original)
+++ doctools/trunk/sphinx/quickstart.py	Sun Apr 27 20:08:55 2008
@@ -126,6 +126,10 @@
 # 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'
 
Modified: doctools/trunk/sphinx/templates/layout.html
==============================================================================
--- doctools/trunk/sphinx/templates/layout.html	(original)
+++ doctools/trunk/sphinx/templates/layout.html	Sun Apr 27 20:08:55 2008
@@ -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') }}" />
Added: doctools/trunk/sphinx/templates/opensearch.xml
==============================================================================
--- (empty file)
+++ doctools/trunk/sphinx/templates/opensearch.xml	Sun Apr 27 20:08:55 2008
@@ -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>
