Closes #1597: Added possibility to return a new template name from html-page-context.

CHANGES

@@ -7,6 +7,9 @@ Incompatible changes
 Features added
 --------------
 
+* #1597: Added possibility to return a new template name from
+  `html-page-context`.
+
 Bugs fixed
 ----------
 

doc/extdev/appapi.rst

@@ -558,8 +558,14 @@ handlers to the events.  Example:
    documents; it will be ``None`` when the page is created from an HTML template
    alone.
 
+   You can return a string from the handler, it will then replace
+   ``'page.html'`` as the HTML template for this page.
+
    .. versionadded:: 0.4
 
+   .. versionchanged:: 1.3
+      The return value can now specify a template name.
+
 .. event:: build-finished (app, exception)
 
    Emitted when a build has finished, before Sphinx exits, usually used for

sphinx/builders/html.py

@@ -767,8 +767,10 @@ class StandaloneHTMLBuilder(Builder):
         self.add_sidebars(pagename, ctx)
         ctx.update(addctx)
 
-        self.app.emit('html-page-context', pagename, templatename,
-                      ctx, event_arg)
+        newtmpl = self.app.emit_firstresult('html-page-context', pagename,
+                                            templatename, ctx, event_arg)
+        if newtmpl:
+            templatename = newtmpl
 
         try:
             output = self.templates.render(templatename, ctx)
@@ -1063,8 +1065,9 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder):
             outfilename = path.join(self.outdir,
                                     os_path(pagename) + self.out_suffix)
 
-        self.app.emit('html-page-context', pagename, templatename,
-                      ctx, event_arg)
+        # we're not taking the return value here, since no template is
+        # actually rendered
+        self.app.emit('html-page-context', pagename, templatename, ctx, event_arg)
 
         ensuredir(path.dirname(outfilename))
         self.dump_context(ctx, outfilename)

sphinx/builders/websupport.py

@@ -105,8 +105,10 @@ class WebSupportBuilder(PickleHTMLBuilder):
         self.add_sidebars(pagename, ctx)
         ctx.update(addctx)
 
-        self.app.emit('html-page-context', pagename, templatename,
-                      ctx, event_arg)
+        newtmpl = self.app.emit_firstresult('html-page-context', pagename,
+                                            templatename, ctx, event_arg)
+        if newtmpl:
+            templatename = newtmpl
 
         # create a dict that will be pickled and used by webapps
         doc_ctx = {