doctools.js 8.0 KB

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