doctools.js 9.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316
  1. /*
  2. * doctools.js
  3. * ~~~~~~~~~~~
  4. *
  5. * Sphinx JavaScript utilities for all documentation.
  6. *
  7. * :copyright: Copyright 2007-2021 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 rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
  85. var bbox = node.parentElement.getBBox();
  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. addItems.push({
  92. "parent": node.parentNode,
  93. "target": rect});
  94. }
  95. }
  96. }
  97. else if (!jQuery(node).is("button, select, textarea")) {
  98. jQuery.each(node.childNodes, function() {
  99. highlight(this, addItems);
  100. });
  101. }
  102. }
  103. var addItems = [];
  104. var result = this.each(function() {
  105. highlight(this, addItems);
  106. });
  107. for (var i = 0; i < addItems.length; ++i) {
  108. jQuery(addItems[i].parent).before(addItems[i].target);
  109. }
  110. return result;
  111. };
  112. /*
  113. * backward compatibility for jQuery.browser
  114. * This will be supported until firefox bug is fixed.
  115. */
  116. if (!jQuery.browser) {
  117. jQuery.uaMatch = function(ua) {
  118. ua = ua.toLowerCase();
  119. var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
  120. /(webkit)[ \/]([\w.]+)/.exec(ua) ||
  121. /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
  122. /(msie) ([\w.]+)/.exec(ua) ||
  123. ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
  124. [];
  125. return {
  126. browser: match[ 1 ] || "",
  127. version: match[ 2 ] || "0"
  128. };
  129. };
  130. jQuery.browser = {};
  131. jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
  132. }
  133. /**
  134. * Small JavaScript module for the documentation.
  135. */
  136. var Documentation = {
  137. init : function() {
  138. this.fixFirefoxAnchorBug();
  139. this.highlightSearchWords();
  140. this.initIndexTable();
  141. if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) {
  142. this.initOnKeyListeners();
  143. }
  144. },
  145. /**
  146. * i18n support
  147. */
  148. TRANSLATIONS : {},
  149. PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; },
  150. LOCALE : 'unknown',
  151. // gettext and ngettext don't access this so that the functions
  152. // can safely bound to a different name (_ = Documentation.gettext)
  153. gettext : function(string) {
  154. var translated = Documentation.TRANSLATIONS[string];
  155. if (typeof translated === 'undefined')
  156. return string;
  157. return (typeof translated === 'string') ? translated : translated[0];
  158. },
  159. ngettext : function(singular, plural, n) {
  160. var translated = Documentation.TRANSLATIONS[singular];
  161. if (typeof translated === 'undefined')
  162. return (n == 1) ? singular : plural;
  163. return translated[Documentation.PLURALEXPR(n)];
  164. },
  165. addTranslations : function(catalog) {
  166. for (var key in catalog.messages)
  167. this.TRANSLATIONS[key] = catalog.messages[key];
  168. this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
  169. this.LOCALE = catalog.locale;
  170. },
  171. /**
  172. * add context elements like header anchor links
  173. */
  174. addContextElements : function() {
  175. $('div[id] > :header:first').each(function() {
  176. $('<a class="headerlink">\u00B6</a>').
  177. attr('href', '#' + this.id).
  178. attr('title', _('Permalink to this headline')).
  179. appendTo(this);
  180. });
  181. $('dt[id]').each(function() {
  182. $('<a class="headerlink">\u00B6</a>').
  183. attr('href', '#' + this.id).
  184. attr('title', _('Permalink to this definition')).
  185. appendTo(this);
  186. });
  187. },
  188. /**
  189. * workaround a firefox stupidity
  190. * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075
  191. */
  192. fixFirefoxAnchorBug : function() {
  193. if (document.location.hash && $.browser.mozilla)
  194. window.setTimeout(function() {
  195. document.location.href += '';
  196. }, 10);
  197. },
  198. /**
  199. * highlight the search words provided in the url in the text
  200. */
  201. highlightSearchWords : function() {
  202. var params = $.getQueryParameters();
  203. var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
  204. if (terms.length) {
  205. var body = $('div.body');
  206. if (!body.length) {
  207. body = $('body');
  208. }
  209. window.setTimeout(function() {
  210. $.each(terms, function() {
  211. body.highlightText(this.toLowerCase(), 'highlighted');
  212. });
  213. }, 10);
  214. $('<p class="highlight-link"><a href="javascript:Documentation.' +
  215. 'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>')
  216. .appendTo($('#searchbox'));
  217. }
  218. },
  219. /**
  220. * init the domain index toggle buttons
  221. */
  222. initIndexTable : function() {
  223. var togglers = $('img.toggler').click(function() {
  224. var src = $(this).attr('src');
  225. var idnum = $(this).attr('id').substr(7);
  226. $('tr.cg-' + idnum).toggle();
  227. if (src.substr(-9) === 'minus.png')
  228. $(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
  229. else
  230. $(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
  231. }).css('display', '');
  232. if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
  233. togglers.click();
  234. }
  235. },
  236. /**
  237. * helper function to hide the search marks again
  238. */
  239. hideSearchWords : function() {
  240. $('#searchbox .highlight-link').fadeOut(300);
  241. $('span.highlighted').removeClass('highlighted');
  242. },
  243. /**
  244. * make the url absolute
  245. */
  246. makeURL : function(relativeURL) {
  247. return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
  248. },
  249. /**
  250. * get the current relative url
  251. */
  252. getCurrentURL : function() {
  253. var path = document.location.pathname;
  254. var parts = path.split(/\//);
  255. $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
  256. if (this === '..')
  257. parts.pop();
  258. });
  259. var url = parts.join('/');
  260. return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
  261. },
  262. initOnKeyListeners: function() {
  263. $(document).keydown(function(event) {
  264. var activeElementType = document.activeElement.tagName;
  265. // don't navigate when in search box, textarea, dropdown or button
  266. if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT'
  267. && activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey
  268. && !event.shiftKey) {
  269. switch (event.keyCode) {
  270. case 37: // left
  271. var prevHref = $('link[rel="prev"]').prop('href');
  272. if (prevHref) {
  273. window.location.href = prevHref;
  274. return false;
  275. }
  276. case 39: // right
  277. var nextHref = $('link[rel="next"]').prop('href');
  278. if (nextHref) {
  279. window.location.href = nextHref;
  280. return false;
  281. }
  282. }
  283. }
  284. });
  285. }
  286. };
  287. // quick alias for translations
  288. _ = Documentation.gettext;
  289. $(document).ready(function() {
  290. Documentation.init();
  291. });