From: Mike Bayer Date: Mon, 23 Jan 2012 21:24:24 +0000 (-0500) Subject: integrate new readthedocs/sqla.org doc build X-Git-Tag: rel_0_7_5~30 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4b0d4a12c72e9f0ef93e7892555177b636180a5d;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git integrate new readthedocs/sqla.org doc build --- diff --git a/doc/build/Makefile b/doc/build/Makefile index 3c336da196..328fa513fd 100644 --- a/doc/build/Makefile +++ b/doc/build/Makefile @@ -21,7 +21,6 @@ help: @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 " 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" @@ -56,13 +55,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 99985666f3..66ccf8dd19 100644 --- a/doc/build/builder/builders.py +++ b/doc/build/builder/builders.py @@ -12,19 +12,17 @@ import re from mako.lookup import TemplateLookup from mako.template import Template from mako import __version__ +import os -if __version__ < "0.4.1": - raise Exception("Mako 0.4.1 or greater is required for " - "documentation build.") +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, @@ -33,12 +31,52 @@ class MakoBridge(TemplateBridge): ] ) + 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) @@ -164,7 +202,8 @@ def setup(app): app.add_lexer('pycon+sql', PyConWithSQLLexer()) app.add_lexer('python+sql', PythonWithSQLLexer()) 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 44884552ec..0a2c5ef440 100644 --- a/doc/build/conf.py +++ b/doc/build/conf.py @@ -55,7 +55,7 @@ master_doc = 'contents' # General information about the project. project = u'SQLAlchemy' -copyright = u'2007-2011, the SQLAlchemy authors and contributors' +copyright = u'2007-2012, 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 @@ -68,7 +68,11 @@ release = "0.7.4" release_date = "December 9, 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')} +<%block name="show_title" filter="util.striptags"> + ${_('Index')} +

${_('Index')}

diff --git a/doc/build/templates/layout.mako b/doc/build/templates/layout.mako index d34e4ef38a..ba3e81c010 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 -<%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} — + % endif + ${docstitle|h} + +
<%block name="headers"> @@ -78,15 +89,10 @@ withsidebar = bool(toc) and current_page_name != 'index'
Release: ${release} | Release Date: ${release_date} - % if self.attr.site_layout: - | Download PDF + % if pdf_url: + | Download PDF % endif - % if self.attr.site_layout and not version.startswith(versions[0][0]): -
- The current version of SQLAlchemy is ${versions[0][0]}. View current SQLAlchemy Documentation -
- % endif
@@ -128,9 +134,7 @@ withsidebar = bool(toc) and current_page_name != 'index'

<%block name="show_title"> - % if title: ${title} - % endif

@@ -157,6 +161,12 @@ withsidebar = bool(toc) and current_page_name != 'index'

% endif + % if rtd: +

Project Versions

+ + % endif +

Quick Search

@@ -175,28 +185,26 @@ withsidebar = bool(toc) and current_page_name != 'index' -<%block name="footer"> - 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"> + + + + + + + + ${parent.headers()} + + +${next.body()} + +<%block name="footer"> +${parent.footer()} + +## Keep this here, so that the RTD logo doesn't stomp on the bottom of the theme. +
+
+
+ + +
+
+ Brought to you by Read the Docs +
    + ## rtd fills this in client side +
+
+
+ + + +% if analytics_code: + + +% endif + + 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>'} -${next.body()} -${''} - -<%text><%def name="style()"> - <%block name="headers"/> - - <%text>${parent.style()} - -<%text> - -<%text><%def name="title()">${capture(self.show_title)|util.striptags} — ${docstitle|h}<%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 @@ ${metatags and metatags or ''} - ${capture(self.show_title)|util.striptags} — ${docstitle|h} + + <%block name="head_title"> + </%block> + <%block name="headers"/> ${next.body()} + <%block name="footer"/> -<%! - local_script_files = [] - site_layout=False -%>