1/* 2 * doctools.js 3 * ~~~~~~~~~~~ 4 * 5 * Sphinx JavaScript utilities for all documentation. 6 * 7 * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. 8 * :license: BSD, see LICENSE for details. 9 * 10 */ 11 12/** 13 * select a different prefix for underscore 14 */ 15$u = _.noConflict(); 16 17/** 18 * make the code below compatible with browsers without 19 * an installed firebug like debugger 20if (!window.console || !console.firebug) { 21 var names = ["log", "debug", "info", "warn", "error", "assert", "dir", 22 "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", 23 "profile", "profileEnd"]; 24 window.console = {}; 25 for (var i = 0; i < names.length; ++i) 26 window.console[names[i]] = function() {}; 27} 28 */ 29 30/** 31 * small helper function to urldecode strings 32 */ 33jQuery.urldecode = function(x) { 34 return decodeURIComponent(x).replace(/\+/g, ' '); 35} 36 37/** 38 * small helper function to urlencode strings 39 */ 40jQuery.urlencode = encodeURIComponent; 41 42/** 43 * This function returns the parsed url parameters of the 44 * current request. Multiple values per key are supported, 45 * it will always return arrays of strings for the value parts. 46 */ 47jQuery.getQueryParameters = function(s) { 48 if (typeof s == 'undefined') 49 s = document.location.search; 50 var parts = s.substr(s.indexOf('?') + 1).split('&'); 51 var result = {}; 52 for (var i = 0; i < parts.length; i++) { 53 var tmp = parts[i].split('=', 2); 54 var key = jQuery.urldecode(tmp[0]); 55 var value = jQuery.urldecode(tmp[1]); 56 if (key in result) 57 result[key].push(value); 58 else 59 result[key] = [value]; 60 } 61 return result; 62}; 63 64/** 65 * small function to check if an array contains 66 * a given item. 67 */ 68jQuery.contains = function(arr, item) { 69 for (var i = 0; i < arr.length; i++) { 70 if (arr[i] == item) 71 return true; 72 } 73 return false; 74}; 75 76/** 77 * highlight a given string on a jquery object by wrapping it in 78 * span elements with the given class name. 79 */ 80jQuery.fn.highlightText = function(text, className) { 81 function highlight(node) { 82 if (node.nodeType == 3) { 83 var val = node.nodeValue; 84 var pos = val.toLowerCase().indexOf(text); 85 if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) { 86 var span = document.createElement("span"); 87 span.className = className; 88 span.appendChild(document.createTextNode(val.substr(pos, text.length))); 89 node.parentNode.insertBefore(span, node.parentNode.insertBefore( 90 document.createTextNode(val.substr(pos + text.length)), 91 node.nextSibling)); 92 node.nodeValue = val.substr(0, pos); 93 } 94 } 95 else if (!jQuery(node).is("button, select, textarea")) { 96 jQuery.each(node.childNodes, function() { 97 highlight(this); 98 }); 99 } 100 } 101 return this.each(function() { 102 highlight(this); 103 }); 104}; 105 106/** 107 * Small JavaScript module for the documentation. 108 */ 109var Documentation = { 110 111 init : function() { 112 this.fixFirefoxAnchorBug(); 113 this.highlightSearchWords(); 114 this.initIndexTable(); 115 }, 116 117 /** 118 * i18n support 119 */ 120 TRANSLATIONS : {}, 121 PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, 122 LOCALE : 'unknown', 123 124 // gettext and ngettext don't access this so that the functions 125 // can safely bound to a different name (_ = Documentation.gettext) 126 gettext : function(string) { 127 var translated = Documentation.TRANSLATIONS[string]; 128 if (typeof translated == 'undefined') 129 return string; 130 return (typeof translated == 'string') ? translated : translated[0]; 131 }, 132 133 ngettext : function(singular, plural, n) { 134 var translated = Documentation.TRANSLATIONS[singular]; 135 if (typeof translated == 'undefined') 136 return (n == 1) ? singular : plural; 137 return translated[Documentation.PLURALEXPR(n)]; 138 }, 139 140 addTranslations : function(catalog) { 141 for (var key in catalog.messages) 142 this.TRANSLATIONS[key] = catalog.messages[key]; 143 this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); 144 this.LOCALE = catalog.locale; 145 }, 146 147 /** 148 * add context elements like header anchor links 149 */ 150 addContextElements : function() { 151 $('div[id] > :header:first').each(function() { 152 $('<a class="headerlink">\u00B6</a>'). 153 attr('href', '#' + this.id). 154 attr('title', _('Permalink to this headline')). 155 appendTo(this); 156 }); 157 $('dt[id]').each(function() { 158 $('<a class="headerlink">\u00B6</a>'). 159 attr('href', '#' + this.id). 160 attr('title', _('Permalink to this definition')). 161 appendTo(this); 162 }); 163 }, 164 165 /** 166 * workaround a firefox stupidity 167 */ 168 fixFirefoxAnchorBug : function() { 169 if (document.location.hash && $.browser.mozilla) 170 window.setTimeout(function() { 171 document.location.href += ''; 172 }, 10); 173 }, 174 175 /** 176 * highlight the search words provided in the url in the text 177 */ 178 highlightSearchWords : function() { 179 var params = $.getQueryParameters(); 180 var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; 181 if (terms.length) { 182 var body = $('div.body'); 183 window.setTimeout(function() { 184 $.each(terms, function() { 185 body.highlightText(this.toLowerCase(), 'highlighted'); 186 }); 187 }, 10); 188 $('<p class="highlight-link"><a href="javascript:Documentation.' + 189 'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>') 190 .appendTo($('#searchbox')); 191 } 192 }, 193 194 /** 195 * init the domain index toggle buttons 196 */ 197 initIndexTable : function() { 198 var togglers = $('img.toggler').click(function() { 199 var src = $(this).attr('src'); 200 var idnum = $(this).attr('id').substr(7); 201 $('tr.cg-' + idnum).toggle(); 202 if (src.substr(-9) == 'minus.png') 203 $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); 204 else 205 $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); 206 }).css('display', ''); 207 if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { 208 togglers.click(); 209 } 210 }, 211 212 /** 213 * helper function to hide the search marks again 214 */ 215 hideSearchWords : function() { 216 $('#searchbox .highlight-link').fadeOut(300); 217 $('span.highlighted').removeClass('highlighted'); 218 }, 219 220 /** 221 * make the url absolute 222 */ 223 makeURL : function(relativeURL) { 224 return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; 225 }, 226 227 /** 228 * get the current relative url 229 */ 230 getCurrentURL : function() { 231 var path = document.location.pathname; 232 var parts = path.split(/\//); 233 $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { 234 if (this == '..') 235 parts.pop(); 236 }); 237 var url = parts.join('/'); 238 return path.substring(url.lastIndexOf('/') + 1, path.length - 1); 239 } 240}; 241 242// quick alias for translations 243_ = Documentation.gettext; 244 245$(document).ready(function() { 246 Documentation.init(); 247}); 248