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

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

diff --git a/doc/build/Makefile b/doc/build/Makefile
index 2ee70dfb8b..e08b72b3fc 100644
--- a/doc/build/Makefile
+++ b/doc/build/Makefile
@@ -18,7 +18,6 @@ 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 "  site-mako  to make sqlalchemy.org Mako files"
 	@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"
@@ -48,13 +47,6 @@ dist-html:
 	@echo
 	@echo "Build finished.  The HTML pages are in ../."
 
-site-mako:
-	$(SPHINXBUILD) -b html -A mako_layout=site $(ALLSPHINXOPTS) $(BUILDDIR)/site
-	$(MAKE) latexpdf
-	cp $(BUILDDIR)/latex/*.pdf $(BUILDDIR)/site/
-	@echo
-	@echo "Build finished. The Mako pages are in $(BUILDDIR)/site."
-
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
diff --git a/doc/build/builder/builders.py b/doc/build/builder/builders.py
index 308bd3b092..66ccf8dd19 100644
--- a/doc/build/builder/builders.py
+++ b/doc/build/builder/builders.py
@@ -11,29 +11,72 @@ 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)
 
@@ -140,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:
@@ -150,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
@@ -158,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/conf.py b/doc/build/conf.py
index 8db196aad0..1bb3c5475e 100644
--- a/doc/build/conf.py
+++ b/doc/build/conf.py
@@ -68,7 +68,11 @@ release = "0.6.8"
 
 release_date = "June 5, 2011"
 
-versions = [('0.7', '07'), ('0.6', '06'), ('0.5', '05')]
+site_base = "http://www.sqlalchemy.org"
+
+# arbitrary number recognized by builders.py, incrementing this 
+# will force a rebuild
+build_number = 2
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css
index 1169a8a975..9a40fd6bf9 100644
--- a/doc/build/static/docs.css
+++ b/doc/build/static/docs.css
@@ -433,3 +433,14 @@ 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 d34e4ef38a..def9585d5b 100644
--- a/doc/build/templates/layout.mako
+++ b/doc/build/templates/layout.mako
@@ -1,5 +1,9 @@
 ## coding: utf-8
 
+<%!
+    local_script_files = []
+%>
+
 <%doc>
     Structural elements are all prefixed with "docs-"
     to prevent conflicts when the structure is integrated into the 
@@ -19,12 +23,19 @@
             docs-copyright
 </%doc>
 
-<%inherit file="${context['mako_layout']}"/>
+<%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">
@@ -78,15 +89,10 @@ withsidebar = bool(toc) and current_page_name != 'index'
     <div id="docs-version-header">
         Release: <span class="version-num">${release}</span> | Release Date: ${release_date}
 
-        % if self.attr.site_layout:
-            | <a href="${pathto('sqlalchemy_' + release.replace('.', '_') + '.pdf', 1)}">Download PDF</a>
+        % if pdf_url:
+        | <a href="${pdf_url}">Download PDF</a>
         % endif
 
-        % if self.attr.site_layout and not version.startswith(versions[0][0]):
-        <div class="version-warning">
-            The current version of SQLAlchemy is ${versions[0][0]}.   <a href="/docs/">View current SQLAlchemy Documentation</a>
-        </div>
-        % endif
     </div>
 
 </div>
@@ -128,9 +134,7 @@ withsidebar = bool(toc) and current_page_name != 'index'
 
         <h2>
             <%block name="show_title">
-            % if title:
                 ${title}
-            % endif
             </%block>
         </h2>
     </div>
@@ -157,6 +161,11 @@ withsidebar = bool(toc) and current_page_name != 'index'
     </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">
@@ -175,28 +184,26 @@ withsidebar = bool(toc) and current_page_name != 'index'
 
 </div>
 
-<%block name="footer">
-    <div id="docs-bottom-navigation" class="docs-navigation-links">
-        % if prevtopic:
-            Previous:
-            <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
-        % endif
-        % if nexttopic:
-            Next:
-            <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
-        % endif
+<div id="docs-bottom-navigation" class="docs-navigation-links">
+    % if prevtopic:
+        Previous:
+        <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+    % endif
+    % if nexttopic:
+        Next:
+        <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+    % endif
 
-        <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 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>
-</%block>
+</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 d4ef4d333f..5ce71ebed5 100644
--- a/doc/build/templates/search.mako
+++ b/doc/build/templates/search.mako
@@ -1,4 +1,4 @@
-<%inherit file="layout.mako"/>
+<%inherit file="${context['layout']}"/>
 
 <%!
     local_script_files = ['_static/searchtools.js']
diff --git a/doc/build/templates/site_base.mako b/doc/build/templates/site_base.mako
deleted file mode 100644
index 88b1f6401b..0000000000
--- a/doc/build/templates/site_base.mako
+++ /dev/null
@@ -1,25 +0,0 @@
-<%text>#coding:utf-8
-<%inherit file="/base.html"/>
-<%page cache_type="file" cached="True"/>
-<%!
-    in_docs=True
-%>
-</%text>
-
-${'<%text>'}
-${next.body()}
-${'</%text>'}
-
-<%text><%def name="style()"></%text>
-    <%block name="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 = []
-    site_layout=True
-%>
diff --git a/doc/build/templates/static_base.mako b/doc/build/templates/static_base.mako
index 9454a1ead1..134c0d00a2 100644
--- a/doc/build/templates/static_base.mako
+++ b/doc/build/templates/static_base.mako
@@ -5,16 +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>
+        <title>
+            <%block name="head_title">
+            </%block>
+        </title>
         <%block name="headers"/>
     </head>
     <body>
         ${next.body()}
+        <%block name="footer"/>
     </body>
 </html>
 
 
-<%!
-    local_script_files = []
-    site_layout=False
-%>