From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 23 Jan 2012 21:17:03 +0000 (-0500)
Subject: integrate new readthedocs/sqla.org doc build
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=08ddc27b520ed82d7cfc882735399123a588f377;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

integrate new readthedocs/sqla.org doc build
---

diff --git a/.hgignore b/.hgignore
new file mode 100644
index 0000000000..b5a6e2ac82
--- /dev/null
+++ b/.hgignore
@@ -0,0 +1,14 @@
+syntax:regexp
+^build/
+^dist/
+^doc/build/output
+.pyc$
+.orig$
+.class$
+.so$
+.egg-info
+.*,cover
+.un~
+\.coverage
+\.DS_Store
+test.cfg
diff --git a/doc/build/Makefile b/doc/build/Makefile
index f7ac2ca576..328fa513fd 100644
--- a/doc/build/Makefile
+++ b/doc/build/Makefile
@@ -5,47 +5,142 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
+BUILDDIR      = output
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d output/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html latex site-mako
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest dist-html site-mako gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  dist-html same as html, but places files in /doc"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  html       to make standalone HTML files"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  dist-html  same as html, but places files in /doc"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	-rm -rf output/*
+	-rm -rf $(BUILDDIR)/*
 
 html:
-	mkdir -p output/html output/doctrees
-	$(SPHINXBUILD) -b html -A mako_layout=html $(ALLSPHINXOPTS) output/html
+	$(SPHINXBUILD) -b html -A mako_layout=html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
-	@echo "Build finished. The HTML pages are in output/html."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
 dist-html:
 	$(SPHINXBUILD) -b html -A mako_layout=html $(ALLSPHINXOPTS) ..
 	@echo
 	@echo "Build finished.  The HTML pages are in ../."
 
-site-mako:
-	mkdir -p output/site output/doctrees
-	$(SPHINXBUILD) -b html -A mako_layout=site $(ALLSPHINXOPTS) output/site
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SQLAlchemy.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SQLAlchemy.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/SQLAlchemy"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SQLAlchemy"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
-	@echo "Build finished. The Mako pages are in output/site."
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 latex:
-	mkdir -p output/latex output/doctrees
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) output/latex
-	cp texinputs/* output/latex/
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	cp texinputs/* $(BUILDDIR)/latex/
 	@echo
-	@echo "Build finished; the LaTeX files are in output/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	cp texinputs/* $(BUILDDIR)/latex/
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
 doctest:
-	$(SPHINXBUILD) -b doctest -d output/doctrees . .
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) .
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/doc/build/builder/builders.py b/doc/build/builder/builders.py
index 1410270ec6..66ccf8dd19 100644
--- a/doc/build/builder/builders.py
+++ b/doc/build/builder/builders.py
@@ -11,31 +11,75 @@ from pygments.formatters import HtmlFormatter, LatexFormatter
 import re
 from mako.lookup import TemplateLookup
 from mako.template import Template
+from mako import __version__
+import os
+
+rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 class MakoBridge(TemplateBridge):
     def init(self, builder, *args, **kw):
         self.jinja2_fallback = BuiltinTemplateLoader()
         self.jinja2_fallback.init(builder, *args, **kw)
-        self.layout = builder.config.html_context.get('mako_layout', 'html')
+
         builder.config.html_context['release_date'] = builder.config['release_date']
-        builder.config.html_context['versions'] = builder.config['versions']
+        builder.config.html_context['site_base'] = builder.config['site_base']
+
         self.lookup = TemplateLookup(directories=builder.config.templates_path,
-            format_exceptions=True, 
+            #format_exceptions=True, 
             imports=[
                 "from builder import util"
             ]
         )
 
+        if rtd:
+            import urllib2
+            template_url = builder.config['site_base'] + "/docs_base.mako"
+            template = urllib2.urlopen(template_url).read()
+            self.lookup.put_string("/rtd_base.mako", template)
+
     def render(self, template, context):
         template = template.replace(".html", ".mako")
         context['prevtopic'] = context.pop('prev', None)
         context['nexttopic'] = context.pop('next', None)
-        context['mako_layout'] = self.layout == 'html' and 'static_base.mako' or 'site_base.mako'
-        # sphinx 1.0b2 doesn't seem to be providing _ for some reason...
+        version = context['version']
+        pathto = context['pathto']
+
+        # RTD layout
+        if rtd:
+            # add variables if not present, such 
+            # as if local test of READTHEDOCS variable
+            if 'MEDIA_URL' not in context:
+                context['MEDIA_URL'] = "http://media.readthedocs.org/"
+            if 'slug' not in context:
+                context['slug'] = context['project'].lower()
+            if 'url' not in context:
+                context['url'] = "/some/test/url"
+            if 'current_version' not in context:
+                context['current_version'] = "latest"
+
+            if 'name' not in context:
+                context['name'] = context['project'].lower()
+
+            context['rtd'] = True
+            context['toolbar'] = True
+            context['layout'] = "rtd_layout.mako"
+            context['base'] = "rtd_base.mako"
+            context['pdf_url'] = "%spdf/%s/%s/%s.pdf" % (
+                    context['MEDIA_URL'],
+                    context['slug'],
+                    context['current_version'],
+                    context['slug']
+            )
+        # local docs layout
+        else:
+            context['rtd'] = False
+            context['toolbar'] = False
+            context['layout'] = "layout.mako"
+            context['base'] = "static_base.mako"
+
         context.setdefault('_', lambda x:x)
         return self.lookup.get_template(template).render_unicode(**context)
 
-
     def render_string(self, template, context):
         # this is used for  .js, .css etc. and we don't have
         # local copies of that stuff here so use the jinja render.
@@ -139,7 +183,7 @@ class PopupLatexFormatter(LatexFormatter):
         for ttype, value in apply_filters(tokensource, [StripDocTestFilter()]):
             if ttype in Token.Sql:
                 if ttype is not Token.Sql.Link and ttype is not Token.Sql.Open:
-                    yield Token.Literal, re.sub(r'(?:[{stop}|\n]*)$', '', value)
+                    yield Token.Literal, re.sub(r'{stop}', '', value)
                 else:
                     continue
             else:
@@ -149,7 +193,7 @@ class PopupLatexFormatter(LatexFormatter):
         LatexFormatter.format(self, self._filter_tokens(tokensource), outfile)
 
 def autodoc_skip_member(app, what, name, obj, skip, options):
-    if what == 'class' and skip and name == '__init__':
+    if what == 'class' and skip and name in ('__init__', '__eq__', '__ne__', '__lt__', '__le__') and obj.__doc__:
         return False
     else:
         return skip
@@ -157,9 +201,10 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
 def setup(app):
     app.add_lexer('pycon+sql', PyConWithSQLLexer())
     app.add_lexer('python+sql', PythonWithSQLLexer())
-    app.connect('autodoc-skip-member', autodoc_skip_member)
     app.add_config_value('release_date', "", True)
-    app.add_config_value('versions', "", True)
+    app.add_config_value('site_base', "", True)
+    app.add_config_value('build_number', "", 1)
+    app.connect('autodoc-skip-member', autodoc_skip_member)
     PygmentsBridge.html_formatter = PopupSQLFormatter
     PygmentsBridge.latex_formatter = PopupLatexFormatter
 
diff --git a/doc/build/builder/util.py b/doc/build/builder/util.py
index 3694d87e43..a9dcff001a 100644
--- a/doc/build/builder/util.py
+++ b/doc/build/builder/util.py
@@ -3,6 +3,10 @@ import re
 def striptags(text):
     return re.compile(r'<[^>]*>').sub('', text)
 
+def go(m):
+    # .html with no anchor if present, otherwise "#" for top of page
+    return m.group(1) or '#'
+
 def strip_toplevel_anchors(text):
-    return re.compile(r'\.html#.*-toplevel').sub('.html', text)
-    
+    return re.compile(r'(\.html)?#[-\w]+-toplevel').sub(go, text)
+
diff --git a/doc/build/conf.py b/doc/build/conf.py
index 04868bc538..a2d4c818b4 100644
--- a/doc/build/conf.py
+++ b/doc/build/conf.py
@@ -1,35 +1,45 @@
 # -*- coding: utf-8 -*-
 #
-# Foo Bar documentation build configuration file, created by
+# SQLAlchemy documentation build configuration file, created by
 # sphinx-quickstart on Wed Nov 26 19:50:10 2008.
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
-# The contents of this file are pickled, so don't put values in the namespace
-# that aren't pickleable (module imports are okay, they're removed automatically).
+# Note that not all possible configuration values are present in this
+# autogenerated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
 import sys, os
 
-# If your extensions are in another directory, add it here. If the directory
-# is relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../../lib'))
 sys.path.insert(0, os.path.abspath('.'))
 
 import sqlalchemy
 
-# General configuration
-# ---------------------
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'builder.builders']
+#extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode',
+#                'sphinx.ext.doctest', 'builder.builders']
+
+extensions = ['sphinx.ext.autodoc',
+                'sphinx.ext.doctest', 'builder.builders']
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['templates']
+# not sure why abspath() is needed here, some users
+# have reported this.
+templates_path = [os.path.abspath('templates')]
+
+nitpicky = True
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -37,14 +47,16 @@ source_suffix = '.rst'
 template_bridge = "builder.builders.MakoBridge"
 
 # The encoding of source files.
-#source_encoding = 'utf-8'
+#source_encoding = 'utf-8-sig'
 
 # The master toctree document.
+# 0.5 docs don't have this newer thing
+#master_doc = 'contents'
 master_doc = 'index'
 
 # General information about the project.
 project = u'SQLAlchemy'
-copyright = u'2007, 2008, 2009, the SQLAlchemy authors and contributors'
+copyright = u'2007-2010, the SQLAlchemy authors and contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -55,9 +67,14 @@ version = "0.5"
 # The full version, including alpha/beta/rc tags.
 release = "0.5.8"
 
-release_date = "Jan 16, 2010"
+release_date = "January 16, 2010"
+
+site_base = "http://www.sqlalchemy.org"
+
+# arbitrary number recognized by builders.py, incrementing this 
+# will force a rebuild
+build_number = 2
 
-versions = [('0.7', '07'), ('0.6', '06'), ('0.5', '05')]
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -69,12 +86,9 @@ versions = [('0.7', '07'), ('0.6', '06'), ('0.5', '05')]
 # Else, today_fmt is used as the format for a strftime call.
 #today_fmt = '%B %d, %Y'
 
-# List of documents that shouldn't be included in the build.
-unused_docs = ['output.txt']
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = ['build']
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['build']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -93,9 +107,26 @@ exclude_trees = ['build']
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# have the "gettext" build generate .pot for each individual
+# .rst
+gettext_compact = False
+
+# -- Options for HTML output ---------------------------------------------------
 
-# Options for HTML output
-# -----------------------
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
 
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
@@ -139,7 +170,7 @@ html_last_updated_fmt = '%m/%d/%Y %H:%M:%S'
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-html_use_modindex = False
+html_domain_indices = False
 
 # If false, no index is generated.
 #html_use_index = True
@@ -150,21 +181,29 @@ html_use_modindex = False
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 #html_copy_source = True
 
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 #html_use_opensearch = ''
 
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = ''
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'FooBardoc'
+htmlhelp_basename = 'SQLAlchemydoc'
 
 #autoclass_content = 'both'
 
-# Options for LaTeX output
-# ------------------------
+# -- Options for LaTeX output --------------------------------------------------
 
 # The paper size ('letter' or 'a4').
 #latex_paper_size = 'letter'
@@ -173,9 +212,9 @@ htmlhelp_basename = 'FooBardoc'
 #latex_font_size = '10pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, document class [howto/manual]).
+# (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'sqlalchemy_%s.tex' % release.replace('.', '_'), ur'SQLAlchemy Documentation',
+  ('sqlalchemy_%s.tex' % release.replace('.', '_'), ur'SQLAlchemy Documentation',
    ur'Mike Bayer', 'manual'),
 ]
 
@@ -187,6 +226,12 @@ latex_documents = [
 # not chapters.
 #latex_use_parts = False
 
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
 # Additional stuff for the LaTeX preamble.
 # sets TOC depth to 2.
 latex_preamble = '\setcounter{tocdepth}{3}'
@@ -195,4 +240,58 @@ latex_preamble = '\setcounter{tocdepth}{3}'
 #latex_appendices = []
 
 # If false, no module index is generated.
-#latex_use_modindex = True
+#latex_domain_indices = True
+
+#latex_elements = {
+#    'papersize': 'letterpaper',
+#    'pointsize': '10pt',
+#}
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'sqlalchemy', u'SQLAlchemy Documentation',
+     [u'SQLAlchemy authors'], 1)
+]
+
+
+# -- Options for Epub output ---------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'SQLAlchemy'
+epub_author = u'SQLAlchemy authors'
+epub_publisher = u'SQLAlchemy authors'
+epub_copyright = u'2011, SQLAlchemy authors'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+#epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
diff --git a/doc/build/requirements.txt b/doc/build/requirements.txt
new file mode 100644
index 0000000000..2951cdd49d
--- /dev/null
+++ b/doc/build/requirements.txt
@@ -0,0 +1 @@
+mako
diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css
index ac6a550fe7..9a40fd6bf9 100644
--- a/doc/build/static/docs.css
+++ b/doc/build/static/docs.css
@@ -1,238 +1,346 @@
-/* documentation section styles */
+/* global */
 
-body, td {
-	font-family: verdana, sans-serif;
-	font-size:.95em;
+body {
+  background-color: #FDFBFC;
+  margin:38px;
+  color:#333333;
 }
 
-body {
-	background-color: #FDFBFC;
-	margin:20px 20px 20px 20px;
+a {
+    font-weight:normal; 
+    text-decoration:none;
 }
 
 form {
     display:inline;
 }
 
-p {
-	margin-top:10px;
-	margin-bottom:10px;
-}
+/* hyperlinks */
 
-a {font-weight:normal; text-decoration:underline;}
-a:link {color:#0000FF;}
-a:visited {color:#0000FF;}
-a:active {color:#0000FF;}
-a:hover {color:#700000;}
+a:link, a:visited, a:active {
+    /*color:#0000FF;*/
+    color: #990000;
+}
+a:hover {
+    color: #FF0000;
+    /*color:#700000;*/
+    text-decoration:underline;
+}
 
+/* paragraph links after sections.
+   These aren't visible until hovering
+   over the <h> tag, then have a 
+   "reverse video" effect over the actual
+   link
+ */
 
-strong a {
-    font-weight: bold;
+a.headerlink {
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+    visibility: hidden;
 }
 
-#search {
-    float:right;
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink {
+    visibility: visible;
 }
 
-#searchform {
-    padding:20px;
+a.headerlink:hover {
+    background-color: #990000;
+    color: white;
 }
 
-#pagecontrol {
-    float:right;
+
+/* Container setup */
+
+#docs-container {
+  max-width:1000px;
 }
 
-.topnav
-{
-	background-color: #fbfbee;
-	border: solid 1px #ccc;
-	padding:10px;
-	margin:10px 0px 10px 0px;
+
+/* header/footer elements */
+
+#docs-header h1 {
+    font-size:20px;
+    color: #222222;
+    margin: 0;
+    padding: 0;
 }
 
-.document {
-	border: solid 1px #ccc;
+#docs-header {
+  font-family:Verdana,sans-serif;
+
+  font-size:.9em;
+
 }
 
-.topnav .prevnext {
-    padding: 5px 0px 0px 0px;
-    font-size: 0.8em
+#docs-top-navigation,
+#docs-bottom-navigation {
+  font-family: Verdana, sans-serif;
+  background-color: #FBFBEE;
+  border: solid 1px #CCC;
+  padding:10px;
+  font-size:.8em;
 }
 
-h1, h2, h3, h4, h5 {
-    font-family:arial,helvetica,sans-serif;
-    font-weight:bold;
+#docs-top-navigation {
+  margin:10px 0px 10px 0px;
+  line-height:1.2em;
 }
 
-.document h1, .document h2, .document h3, .document h4, .document h5 {
-    font-size: 1.4em;
+.docs-navigation-links {
+  font-family:Verdana,sans-serif;
 }
 
-.document img {
-    display:block;
-    margin: 0 auto;
+#docs-bottom-navigation {
+    float:right;
+    margin: 1em 0 1em 5px;
 }
 
-.document h1 {
-    display:none;
+#docs-copyright {
+    font-size:.85em;
+    padding:5px 0px;
 }
 
-h1 {
-    font: normal 20px/22px arial,helvetica,sans-serif;
-    color: #222;
-    padding:0px;
-    margin:0px;   
+#docs-header h1,
+#docs-top-navigation h1,
+#docs-top-navigation h2 {
+  font-family:Tahoma,Geneva,sans-serif;
+  font-weight:normal;
 }
 
-.topnav h2 {
-    margin:26px 4px 0px 5px;
-    font-family:arial,helvetica,sans-serif;
+#docs-top-navigation h2 {
+    margin:16px 4px 7px 5px;
     font-size:1.6em;
-    font-weight:normal;
-    line-height:1.6em;  
 }
 
-.topnav h3 {
-    font-weight: bold;
-    font-size: 1.4em;
-    margin:0px;
-    display:inline;
-    font-family:verdana,sans-serif;
+#docs-search {
+    float:right;
 }
 
-.topnav li,
-li.toctree-l1,
-li.toctree-l1 li
-{
-    list-style-type:disc;
-    margin:0px;
+#docs-top-page-control {
+  float:right;
+  width:350px;
+}
+
+#docs-top-page-control ul {
+  padding:0;
+  margin:0;
+}
+
+#docs-top-page-control li {
+    font-size:.9em;
+    list-style-type:none;
     padding:1px 8px;
 }
 
 
-.topnav li ul, 
-li.toctree-l1 ul
-{
-    padding:0px 0px 0px 20px;
+#docs-container .version-num {
+    font-weight: bold;
 }
 
-.topnav li ul li li, 
-li.toctree-l1 ul li li
-{
-    /*font-size:.90em;*/
+
+/* content container, sidebar */
+
+#docs-body-container {
+  background-color:#EFEFEF;
+  border: solid 1px #CCC;
+
 }
 
-.sourcelink {
-    font-size:.8em;
-    text-align:right;
-    padding-top:10px;
+#docs-body,
+#docs-sidebar
+ {
+  /*font-family: helvetica, arial, sans-serif;
+  font-size:.9em;*/
+
+  font-family: Verdana, sans-serif;
+  font-size:.85em;
+  line-height:1.5em;
+
 }
 
-.section {
-    line-height: 1.5em;
-    padding:8px 10px 20px 10px;
-    margin:10px 0px 0px;
+#docs-sidebar > ul {
+  font-size:.85em;
 }
 
-.section .section {
-    margin:0px 0px 0px 0px;
-    padding: 0px;
+#docs-sidebar {
+  float:left;
+  width:212px;
+  padding: 10px 0 0 15px;
+  font-size:.85em;
 }
 
-.section .section .section {
-    margin:0px 0px 0px 20px;
+#docs-sidebar h3, #docs-sidebar h4 {
+    background-color: #DDDDDD;
+    color: #222222;
+    font-family: Verdana,sans-serif;
+    font-size: 1.1em;
+    font-weight: normal;
+    margin: 10px 0 0 -15px;
+    padding: 5px 10px 5px 10px;
+    text-shadow: 1px 1px 0 white;
+    width:210px;
 }
 
-.section .section .section .section {
-    margin:0px 0px 0px 20px;
+#docs-sidebar h3 a, #docs-sidebar h4 a {
+  color: #222222;
+}
+#docs-sidebar ul {
+  margin: 10px 10px 10px 0px;
+  padding: 0;
+  list-style: none outside none;
 }
 
 
-.bottomnav {
-    background-color:#FBFBEE;
-    border:1px solid #CCCCCC;
-    float:right;
-    margin: 1em 0 1em 5px;
-    padding:10px;
+#docs-sidebar ul ul {
+    margin-bottom: 0;
+    margin-top: 0;
+    list-style: square outside none;
+    margin-left: 20px;
 }
 
-.totoc {
-    
+#docs-body {
+  background-color:#FFFFFF;
+  padding:1px 10px 10px 10px;
 }
 
-.doc_copyright {
-    font-size:.85em;
-    padding:10px 0px 10px 0px;
+#docs-body.withsidebar {
+  margin: 0 0 0 230px;
+  border-left:3px solid #DFDFDF;
+}
+
+#docs-body h1,
+#docs-body h2,
+#docs-body h3,
+#docs-body h4 {
+  font-family:Helvetica, Arial, sans-serif;
+}
+
+#docs-body h1 {
+  /* hide the <h1> for each content section. */
+  display:none;
+  font-size:1.8em;
+}
+
+#docs-body h2 {
+  font-size:1.6em;
+}
+
+#docs-body h3 {
+  font-size:1.4em;
 }
 
-pre {
-	background-color: #f0f0f0;	
-	border: solid 1px #ccc;
-	padding:10px;
-	margin: 5px 5px 5px 5px;
-	overflow:auto;
-	line-height:1.3em;
+/* SQL popup, code styles */
+
+.highlight {
+  background:none;
+}
+
+#docs-container pre {
+  font-size:1.2em;
+}
+
+#docs-container .pre {
+  font-size:1.1em;
+}
+
+#docs-container pre {
+  background-color: #f0f0f0;  
+  border: solid 1px #ccc;
+  box-shadow: 2px 2px 3px #DFDFDF;
+  padding:10px;
+  margin: 5px 0px 5px 0px;
+  overflow:auto;
+  line-height:1.3em;
 }
 
 .popup_sql, .show_sql
 {
-    background-color: #fbfbee;
-    padding:0px 10px;
-    margin:0px -10px;
+    background-color: #FBFBEE;
+    padding:5px 10px;
+    margin:10px -5px;
+    border:1px dashed;
 }
 
-.sql_link
+/* the [SQL] links used to display SQL */
+#docs-container .sql_link
 {
-	font-weight:normal;
-	font-family: arial, sans-serif;
-    text-transform: uppercase;
-	font-size: 0.9em;
-	color:#666;
-	border:1px solid;
-	padding:1px 2px 1px 2px;
-	margin:0px 10px 0px 15px;
-	float:right;
-	line-height:1.2em;
-}
-
-#docs a.sql_link, .sql_link
+  font-weight:normal;
+  font-family: arial, sans-serif;
+  font-size:.9em;
+  text-transform: uppercase;
+  color:#990000;
+  border:1px solid;
+  padding:1px 2px 1px 2px;
+  margin:0px 10px 0px 15px;
+  float:right;
+  line-height:1.2em;
+}
+
+#docs-container a.sql_link, 
+#docs-container .sql_link
 {
     text-decoration: none;
     padding:1px 2px;
 }
 
-#docs a.sql_link:hover {
+#docs-container a.sql_link:hover {
     text-decoration: none;
     color:#fff;
     border:1px solid #900;
     background-color: #900;
 }
 
-.versionheader {
-    margin-top: 0.5em;
+/* docutils-specific elements */
+
+th.field-name {
+    text-align:right;
 }
-.versionnum {
-    font-weight: bold;
+
+div.note, div.warning, p.deprecated, div.topic  {
+    background-color:#EEFFEF;
 }
 
-.prerelease {
-    border: solid #c25757 2px;
-    border-radius: 4px;
-    -moz-border-radius: 4px;
-    -webkit-border-radius: 4px;
-    background-color: #c21a1a;
-    color: white;
-    padding: 0.05em 0.2em;
+
+div.admonition, div.topic, p.deprecated {
+    border:1px solid #CCCCCC;
+    padding:5px 10px;
+    font-size:.9em;
+    box-shadow: 2px 2px 3px #DFDFDF;
+}
+
+div.warning .admonition-title {
+    color:#FF0000;
+}
+
+div.admonition .admonition-title, div.topic .topic-title {
+    font-weight:bold;
+}
+
+.viewcode-back, .viewcode-link {
+    float:right;
 }
 
 dl.function > dt,
-dl.class > dt
+dl.attribute > dt,
+dl.classmethod > dt,
+dl.method > dt,
+dl.class > dt,
+dl.exception > dt
 {
     background-color:#F0F0F0;
-    margin:0px -10px;
+    margin:25px -10px 10px 10px;
     padding: 0px 10px;
 }
 
+
 dt:target, span.highlight {
     background-color:#FBE54E;
 }
@@ -278,16 +386,61 @@ tt {
     padding:0 1px;
 }
 
-@media print {
-  #nav { display: none; }
-  #pagecontrol { display: none; }
-  .topnav .prevnext { display: none; }
-  .bottomnav { display: none; }
-  .totoc { display: none; }
-  .topnav ul li a { text-decoration: none; color: #000; }
-}
-
 /* syntax highlighting overrides */
 .k, .kn {color:#0908CE;}
 .o {color:#BF0005;}
 .go {color:#804049;}
+
+
+/* special "index page" sections 
+   with specific formatting
+*/
+
+div#sqlalchemy-documentation {
+  font-size:.95em;
+}
+div#sqlalchemy-documentation em {
+  font-style:normal;
+}
+div#sqlalchemy-documentation .rubric{
+  font-size:14px;
+  background-color:#EEFFEF;
+  padding:5px;
+  border:1px solid #BFBFBF;
+}
+div#sqlalchemy-documentation a, div#sqlalchemy-documentation li {
+  padding:5px 0px;
+}
+
+div#getting-started {
+  border-bottom:1px solid;
+}
+
+div#sqlalchemy-documentation div#sqlalchemy-orm {
+  float:left;
+  width:48%;
+}
+
+div#sqlalchemy-documentation div#sqlalchemy-core {
+  float:left;
+  width:48%;
+  margin:0;
+  padding-left:10px;
+  border-left:1px solid;
+}
+
+div#dialect-documentation {
+  border-top:1px solid;
+  /*clear:left;*/
+}
+
+div .versionwarning,
+div .version-warning {
+  font-size:12px;
+  font-color:red;
+  border:1px solid;
+  padding:4px 4px;
+  margin:8px 0px 2px 0px;
+  background:#FFBBBB;
+}
+
diff --git a/doc/build/static/init.js b/doc/build/static/init.js
index fb250480b4..cd4dac6b91 100644
--- a/doc/build/static/init.js
+++ b/doc/build/static/init.js
@@ -1,7 +1,13 @@
-$(document).ready(function(){
+
+function initSQLPopups() {
     $('div.popup_sql').hide();
     $('a.sql_link').click(function() {
         $(this).nextAll('div.popup_sql:first').toggle();
         return false;
     })
+}
+
+$(document).ready(function() {
+    initSQLPopups();
 });
+
diff --git a/doc/build/templates/genindex.mako b/doc/build/templates/genindex.mako
index b1a44f56d0..fce20f28db 100644
--- a/doc/build/templates/genindex.mako
+++ b/doc/build/templates/genindex.mako
@@ -1,6 +1,8 @@
-<%inherit file="layout.mako"/>
+<%inherit file="${context['layout']}"/>
 
-<%def name="show_title()">${_('Index')}</%def>
+<%block name="show_title" filter="util.striptags">
+    ${_('Index')}
+</%block>
 
    <h1 id="index">${_('Index')}</h1>
 
diff --git a/doc/build/templates/layout.mako b/doc/build/templates/layout.mako
index 505a7a758b..6491bd1d1f 100644
--- a/doc/build/templates/layout.mako
+++ b/doc/build/templates/layout.mako
@@ -1,7 +1,44 @@
 ## coding: utf-8
-<%inherit file="${context['mako_layout']}"/>
 
-<%def name="headers()">
+<%!
+    local_script_files = []
+%>
+
+<%doc>
+    Structural elements are all prefixed with "docs-"
+    to prevent conflicts when the structure is integrated into the 
+    main site.
+    
+    docs-container ->
+        docs-header ->
+            docs-search
+            docs-version-header
+        docs-top-navigation
+            docs-top-page-control
+            docs-navigation-banner
+        docs-body-container ->
+            docs-sidebar
+            docs-body
+        docs-bottom-navigation
+            docs-copyright
+</%doc>
+
+<%inherit file="${context['base']}"/>
+
+<%
+withsidebar = bool(toc) and current_page_name != 'index'
+%>
+
+<%block name="head_title">
+    % if current_page_name != 'index':
+    ${capture(self.show_title) | util.striptags} &mdash; 
+    % endif
+    ${docstitle|h}
+</%block>
+
+<div id="docs-container">
+
+<%block name="headers">
     <link rel="stylesheet" href="${pathto('_static/pygments.css', 1)}" type="text/css" />
     <link rel="stylesheet" href="${pathto('_static/docs.css', 1)}" type="text/css" />
 
@@ -35,89 +72,120 @@
     % if prevtopic:
         <link rel="prev" title="${prevtopic['title']|util.striptags}" href="${prevtopic['link']|h}" />
     % endif
-    ${self.extrahead()}
-</%def>
-<%def name="extrahead()"></%def>
-
-        <h1>${docstitle|h}</h1>
-
-        <div id="search">
-        Search:
-        <form class="search" action="${pathto('search')}" method="get">
-          <input type="text" name="q" size="18" /> <input type="submit" value="${_('Search')}" />
-          <input type="hidden" name="check_keywords" value="yes" />
-          <input type="hidden" name="area" value="default" />
-        </form>
-        </div>
-
-        <div class="versionheader">
-            Release: <span class="versionnum">${release}</span> | Release Date: ${release_date}
-            % if not version.startswith(versions[0][0]):
-            <div class="versionwarning">
-                The current version of SQLAlchemy is ${versions[0][0]}.   <a href="/docs/">View current SQLAlchemy Documentation</a>
-            </div>
-            % endif
-        </div>
-        <div class="clearboth"></div>
-
-        <div class="topnav">
-            <div id="pagecontrol">
-                <a href="${pathto('reference/index')}">API Reference</a>
-                |
-                <a href="${pathto('genindex')}">Index</a>
-
-                % if sourcename:
-                <div class="sourcelink">(<a href="${pathto('_sources/' + sourcename, True)|h}">${_('view source')})</div>
-                % endif
-            </div>
-
-            <div class="navbanner">
-                <a class="totoc" href="${pathto(master_doc)}">Table of Contents</a>
-                % if parents:
-                    % for parent in parents:
-                        » <a href="${parent['link']|h}" title="${parent['title']}">${parent['title']}</a>
-                    % endfor
-                % endif
-                % if current_page_name != master_doc:
-                » ${self.show_title()} 
-                % endif
-
-                ${prevnext()}
-                <h2>
-                    ${self.show_title()} 
-                </h2>
-            </div>
-            % if display_toc and not current_page_name.startswith('index'):
-                ${toc}
+</%block>
+
+<div id="docs-header">
+    <h1>${docstitle|h}</h1>
+
+    <div id="docs-search">
+    Search:
+    <form class="search" action="${pathto('search')}" method="get">
+      <input type="text" name="q" size="18" /> <input type="submit" value="${_('Search')}" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    </div>
+
+    <div id="docs-version-header">
+        Release: <span class="version-num">${release}</span> | Release Date: ${release_date}
+
+        % if pdf_url:
+        | <a href="${pdf_url}">Download PDF</a>
+        % endif
+
+    </div>
+
+</div>
+
+<div id="docs-top-navigation">
+    <div id="docs-top-page-control" class="docs-navigation-links">
+        <ul>
+        % if prevtopic:
+            <li>Prev:
+            <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+            </li>
+        % endif
+        % if nexttopic:
+            <li>Next:
+            <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+            </li>
+        % endif
+
+        <li>
+            <a href="${pathto('index')}">Table of Contents</a> |
+            <a href="${pathto('genindex')}">Index</a>
+            % if sourcename:
+            | <a href="${pathto('_sources/' + sourcename, True)|h}">${_('view source')}
             % endif
-            <div class="clearboth"></div>
-        </div>
-
-        <div class="document">
-            <div class="body">
-                ${next.body()}
-            </div>
-        </div>
-
-        <%def name="footer()">
-            <div class="bottomnav">
-                ${prevnext()}
-                <div class="doc_copyright">
-                % if hasdoc('copyright'):
-                    &copy; <a href="${pathto('copyright')}">Copyright</a> ${copyright|h}.
-                % else:
-                    &copy; Copyright ${copyright|h}.
-                % endif
-                % if show_sphinx:
-                    Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> ${sphinx_version|h}.
-                % endif
-                </div>
-            </div>
-        </%def>
-        ${self.footer()}
-
-<%def name="prevnext()">
-<div class="prevnext">
+        </li>
+        </ul>
+    </div>
+
+    <div id="docs-navigation-banner">
+        <a href="${pathto('index')}">${docstitle|h}</a>
+        % if parents:
+            % for parent in parents:
+                » <a href="${parent['link']|h}" title="${parent['title']}">${parent['title']}</a>
+            % endfor
+        % endif
+        % if current_page_name != 'index':
+        » ${self.show_title()} 
+        % endif
+
+        <h2>
+            <%block name="show_title">
+                ${title}
+            </%block>
+        </h2>
+    </div>
+
+</div>
+
+<div id="docs-body-container">
+
+% if withsidebar:
+    <div id="docs-sidebar">
+    <h3><a href="${pathto('index')}">Table of Contents</a></h3>
+    ${toc}
+
+    % if prevtopic:
+    <h4>Previous Topic</h4>
+    <p>
+    <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+    </p>
+    % endif
+    % if nexttopic:
+    <h4>Next Topic</h4>
+    <p>
+    <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+    </p>
+    % endif
+
+    % if rtd:
+    <h4>Project Versions</h4>
+    <ul class="version-listing">
+    </ul>
+    % endif
+
+    <h4>Quick Search</h4>
+    <p>
+    <form class="search" action="${pathto('search')}" method="get">
+      <input type="text" name="q" size="18" /> <input type="submit" value="${_('Search')}" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    </p>
+
+    </div>
+% endif
+
+    <div id="docs-body" class="${'withsidebar' if withsidebar else ''}" >
+        ${next.body()}
+    </div>
+
+</div>
+
+<div id="docs-bottom-navigation" class="docs-navigation-links">
     % if prevtopic:
         Previous:
         <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
@@ -126,12 +194,17 @@
         Next:
         <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
     % endif
-</div>
-</%def>
 
-<%def name="show_title()">
-% if title:
-    ${title}
-% endif
-</%def>
+    <div id="docs-copyright">
+    % if hasdoc('copyright'):
+        &copy; <a href="${pathto('copyright')}">Copyright</a> ${copyright|h}.
+    % else:
+        &copy; Copyright ${copyright|h}.
+    % endif
+    % if show_sphinx:
+        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> ${sphinx_version|h}.
+    % endif
+    </div>
+</div>
 
+</div>
diff --git a/doc/build/templates/page.mako b/doc/build/templates/page.mako
index e0f98cf648..61cf9a05ed 100644
--- a/doc/build/templates/page.mako
+++ b/doc/build/templates/page.mako
@@ -1,2 +1,2 @@
-<%inherit file="layout.mako"/>
+<%inherit file="${context['layout']}"/>
 ${body| util.strip_toplevel_anchors}
\ No newline at end of file
diff --git a/doc/build/templates/rtd_layout.mako b/doc/build/templates/rtd_layout.mako
new file mode 100644
index 0000000000..8c0ed1fd55
--- /dev/null
+++ b/doc/build/templates/rtd_layout.mako
@@ -0,0 +1,164 @@
+<%inherit file="/layout.mako"/>
+
+<%
+    newscript = []
+    # strip out script files that RTD wants to provide
+    for script in script_files:
+        for token in ("jquery.js", "underscore.js", "doctools.js"):
+            if token in script:
+                break
+        else:
+            newscript.append(script)
+    script_files[:] = newscript
+%>
+
+<%block name="headers">
+<!-- RTD <head> -->
+<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
+<script type="text/javascript" src="${MEDIA_URL}javascript/underscore.js"></script>
+<script type="text/javascript" src="${MEDIA_URL}javascript/doctools.js"></script>
+<script type="text/javascript" src="${MEDIA_URL}javascript/searchtools.js"></script>
+  <script type="text/javascript">
+    var doc_version = "${current_version}";
+    var doc_slug = "${slug}";
+    var static_root = "${pathto('_static', 1)}"
+  </script>
+<!-- end RTD <head> -->
+    ${parent.headers()}
+</%block>
+
+${next.body()}
+
+<%block name="footer">
+${parent.footer()}
+ <!-- End original user content -->
+## Keep this here, so that the RTD logo doesn't stomp on the bottom of the theme.
+<br>
+<br>
+<br>
+
+<style type="text/css">
+  .badge {
+    position: fixed;
+    display: block;
+    bottom: 5px;
+    height: 40px;
+    text-indent: -9999em;
+    border-radius: 3px;
+    -moz-border-radius: 3px;
+    -webkit-border-radius: 3px;
+    box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 1px 0 rgba(255, 255, 255, 0.2) inset;
+    -moz-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 1px 0 rgba(255, 255, 255, 0.2) inset;
+    -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 1px 0 rgba(255, 255, 255, 0.2) inset;
+  }
+  #version_menu {
+    position: fixed;
+    display: none;
+    bottom: 11px;
+    right: 166px;
+    list-style-type: none;
+    margin: 0;
+  }
+  .footer_popout:hover #version_menu {
+    display: block;
+  }
+  #version_menu li {
+    display: block;
+    float: right;
+  }
+  #version_menu li a {
+    display: block;
+    padding: 6px 10px 4px 10px;
+    margin: 7px 7px 0 0;
+    font-weight: bold;
+    font-size: 14px;
+    height: 20px;
+    line-height: 17px;
+    text-decoration: none;
+    color: #fff;
+    background: #8ca1af url(../images/gradient-light.png) bottom left repeat-x;
+    border-radius: 3px;
+    -moz-border-radius: 3px;
+    -webkit-border-radius: 3px;
+    box-shadow: 0 1px 1px #465158;
+    -moz-box-shadow: 0 1px 1px #465158;
+    -webkit-box-shadow: 0 1px 1px #465158;
+    text-shadow: 0 1px 1px rgba(0, 0, 0, 0.5);
+  }
+  #version_menu li a:hover {
+    text-decoration: none;
+    background-color: #697983;
+    box-shadow: 0 1px 0px #465158;
+    -moz-box-shadow: 0 1px 0px #465158;
+    -webkit-box-shadow: 0 1px 0px #465158;
+  }
+  .badge.rtd {
+    background: #257597 url(http://media.readthedocs.org/images/badge-rtd.png) top left no-repeat;
+    border: 1px solid #282E32;
+    width: 160px;
+    right: 5px;
+  }
+  .badge.revsys { background: #465158 url(http://media.readthedocs.org/images/badge-revsys.png) top left no-repeat;
+    border: 1px solid #1C5871;
+    width: 290px;
+    right: 173px;
+  }
+  .badge.revsys-inline-sponsored {
+    position: inherit;
+    margin-left: auto;
+    margin-right: 175px;
+    margin-bottom: 5px;
+    background: #465158 url(http://media.readthedocs.org/images/badge-revsys.png) top left no-repeat;
+    border: 1px solid #1C5871;
+    width: 290px;
+    right: 173px;
+  }
+  .badge.revsys-inline {
+    position: inherit;
+    margin-left: auto;
+    margin-right: 175px;
+    margin-bottom: 5px;
+    background: #465158 url(http://media.readthedocs.org/images/badge-revsys-sm.png) top left no-repeat;
+    border: 1px solid #1C5871;
+    width: 205px;
+    right: 173px;
+  }
+
+</style>
+<div class="rtd_doc_footer">
+  <div class="footer_popout">
+    <a href="http://readthedocs.org/projects/${slug}/?fromdocs=${slug}" class="badge rtd">Brought to you by Read the Docs</a>
+    <ul id="version_menu">
+         ## rtd fills this in client side
+    </ul>
+  </div>
+</div>
+<!-- RTD Analytics Code -->
+<script type="text/javascript">
+  var _gaq = _gaq || [];
+  _gaq.push(['_setAccount', 'UA-17997319-1']);
+  _gaq.push(['_trackPageview']);
+
+  (function() {
+    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+  })();
+</script>
+
+% if analytics_code:
+<!-- User Analytics Code -->
+<script type="text/javascript">
+  var _gaq = _gaq || [];
+  _gaq.push(['_setAccount', '${analytics_code}']);
+  _gaq.push(['_trackPageview']);
+
+  (function() {
+    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+  })();
+</script>
+% endif
+
+</%block>
diff --git a/doc/build/templates/search.mako b/doc/build/templates/search.mako
index dfad4d0e56..5ce71ebed5 100644
--- a/doc/build/templates/search.mako
+++ b/doc/build/templates/search.mako
@@ -1,9 +1,11 @@
-<%inherit file="layout.mako"/>
+<%inherit file="${context['layout']}"/>
 
 <%!
     local_script_files = ['_static/searchtools.js']
 %>
-<%def name="show_title()">${_('Search')}</%def>
+<%block name="show_title">
+    ${_('Search')}
+</%block>
 
 <div id="searchform">
 <h3>Enter Search Terms:</h3>
@@ -16,7 +18,7 @@
 
 <div id="search-results"></div>
 
-<%def name="footer()">
+<%block name="footer">
     ${parent.footer()}
     <script type="text/javascript" src="searchindex.js"></script>
-</%def>
+</%block>
diff --git a/doc/build/templates/site_base.mako b/doc/build/templates/site_base.mako
deleted file mode 100644
index 1bc15affc4..0000000000
--- a/doc/build/templates/site_base.mako
+++ /dev/null
@@ -1,28 +0,0 @@
-<%text>#coding:utf-8
-<%inherit file="/base.html"/>
-<%page cache_type="file" cached="True"/>
-<%!
-    in_docs=True
-%>
-</%text>
-
-<div style="text-align:right">
-<b>Quick Select:</b> ${" | ".join('<a href="/docs/%s/">%s</a>' % (link, vers) for vers, link in versions)}<br/>
-<b>PDF Download:</b> <a href="${pathto('sqlalchemy_' + release.replace('.', '_') + '.pdf', 1)}">download</a>
-</div>
-
-${'<%text>'}
-${next.body()}
-${'</%text>'}
-
-<%text><%def name="style()"></%text>
-    ${self.headers()}
-    <%text>${parent.style()}</%text>
-    <link href="/css/site_docs.css" rel="stylesheet" type="text/css"></link>
-<%text></%def></%text>
-
-<%text><%def name="title()"></%text>${capture(self.show_title)|util.striptags} &mdash; ${docstitle|h}<%text></%def></%text>
-
-<%!
-    local_script_files = []
-%>
diff --git a/doc/build/templates/static_base.mako b/doc/build/templates/static_base.mako
index eaca5ced64..134c0d00a2 100644
--- a/doc/build/templates/static_base.mako
+++ b/doc/build/templates/static_base.mako
@@ -5,15 +5,16 @@
     <head>
         <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
         ${metatags and metatags or ''}
-        <title>${capture(self.show_title)|util.striptags} &mdash; ${docstitle|h}</title>
-        ${self.headers()}
+        <title>
+            <%block name="head_title">
+            </%block>
+        </title>
+        <%block name="headers"/>
     </head>
     <body>
         ${next.body()}
+        <%block name="footer"/>
     </body>
 </html>
 
 
-<%!
-    local_script_files = []
-%>