doctools.js 9.1 KB

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