From bd3f021f64c447e61c157a63d078b8e03b3dda21 Mon Sep 17 00:00:00 2001 From: "georg.brandl" Date: Sun, 27 Apr 2008 18:08:55 +0000 Subject: Add OpenSearch capability. --- CHANGES | 5 ++++- TODO | 1 - doc/config.rst | 8 +++++++- sphinx/builder.py | 18 ++++++++++++++---- sphinx/config.py | 1 + sphinx/quickstart.py | 4 ++++ sphinx/templates/layout.html | 5 +++++ sphinx/templates/opensearch.xml | 13 +++++++++++++ 8 files changed, 48 insertions(+), 7 deletions(-) create mode 100644 sphinx/templates/opensearch.xml diff --git a/CHANGES b/CHANGES index fe85a13c..91dc4503 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/TODO b/TODO index a083158f..4ea32900 100644 --- a/TODO +++ b/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? diff --git a/doc/config.rst b/doc/config.rst index 7378270f..3de76e8d 100644 --- a/doc/config.rst +++ b/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 ` description file will be + output, and all pages will contain a ```` tag referring to it. + The default is ``False``. .. confval:: html_translator_class diff --git a/sphinx/builder.py b/sphinx/builder.py index 39be00b6..effe9c0a 100644 --- a/sphinx/builder.py +++ b/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,7 +568,8 @@ class StandaloneHTMLBuilder(Builder): 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 @@ 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) - 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: diff --git a/sphinx/config.py b/sphinx/config.py index ffb1ab47..b1d8aa19 100644 --- a/sphinx/config.py +++ b/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), diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index f160aeee..3198f41c 100644 --- a/sphinx/quickstart.py +++ b/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/. #html_copy_source = True +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. +#html_use_opensearch = False + # Output file base name for HTML help builder. htmlhelp_basename = '%(project)sdoc' diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index 71a8d026..5a5ca26c 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/templates/layout.html @@ -62,6 +62,11 @@ {%- endif %} + {%- if use_opensearch %} + + {%- endif %} {%- block rellinks %} {%- if hasdoc('about') %} diff --git a/sphinx/templates/opensearch.xml b/sphinx/templates/opensearch.xml new file mode 100644 index 00000000..1f14e9bd --- /dev/null +++ b/sphinx/templates/opensearch.xml @@ -0,0 +1,13 @@ + + + {{ project }} + {{ docstitle }} + Search {{ docstitle }} + utf-8 + + + + + +{% block extra %}{# Put e.g. an element here. #}{% endblock %} + -- cgit v1.2.1