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 /**

    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

    20 if (!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  */

    33 jQuery.urldecode = function(x) {

    34   return decodeURIComponent(x).replace(/\+/g, ' ');

    35 };

    36 

    37 /**

    38  * small helper function to urlencode strings

    39  */

    40 jQuery.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  */

    47 jQuery.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  * highlight a given string on a jquery object by wrapping it in

    66  * span elements with the given class name.

    67  */

    68 jQuery.fn.highlightText = function(text, className) {

    69   function highlight(node, addItems) {

    70     if (node.nodeType === 3) {

    71       var val = node.nodeValue;

    72       var pos = val.toLowerCase().indexOf(text);

    73       if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) {

    74         var span;

    75         var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");

    76         if (isInSVG) {

    77           span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");

    78         } else {

    79           span = document.createElement("span");

    80           span.className = className;

    81         }

    82         span.appendChild(document.createTextNode(val.substr(pos, text.length)));

    83         node.parentNode.insertBefore(span, node.parentNode.insertBefore(

    84           document.createTextNode(val.substr(pos + text.length)),

    85           node.nextSibling));

    86         node.nodeValue = val.substr(0, pos);

    87         if (isInSVG) {

    88           var bbox = span.getBBox();

    89           var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");

    90        	  rect.x.baseVal.value = bbox.x;

    91           rect.y.baseVal.value = bbox.y;

    92           rect.width.baseVal.value = bbox.width;

    93           rect.height.baseVal.value = bbox.height;

    94           rect.setAttribute('class', className);

    95           var parentOfText = node.parentNode.parentNode;

    96           addItems.push({

    97               "parent": node.parentNode,

    98               "target": rect});

    99         }

   100       }

   101     }

   102     else if (!jQuery(node).is("button, select, textarea")) {

   103       jQuery.each(node.childNodes, function() {

   104         highlight(this, addItems);

   105       });

   106     }

   107   }

   108   var addItems = [];

   109   var result = this.each(function() {

   110     highlight(this, addItems);

   111   });

   112   for (var i = 0; i < addItems.length; ++i) {

   113     jQuery(addItems[i].parent).before(addItems[i].target);

   114   }

   115   return result;

   116 };

   117 

   118 /*

   119  * backward compatibility for jQuery.browser

   120  * This will be supported until firefox bug is fixed.

   121  */

   122 if (!jQuery.browser) {

   123   jQuery.uaMatch = function(ua) {

   124     ua = ua.toLowerCase();

   125 

   126     var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||

   127       /(webkit)[ \/]([\w.]+)/.exec(ua) ||

   128       /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||

   129       /(msie) ([\w.]+)/.exec(ua) ||

   130       ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||

   131       [];

   132 

   133     return {

   134       browser: match[ 1 ] || "",

   135       version: match[ 2 ] || "0"

   136     };

   137   };

   138   jQuery.browser = {};

   139   jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;

   140 }

   141 

   142 /**

   143  * Small JavaScript module for the documentation.

   144  */

   145 var Documentation = {

   146 

   147   init : function() {

   148     this.fixFirefoxAnchorBug();

   149     this.highlightSearchWords();

   150     this.initIndexTable();

   151     

   152   },

   153 

   154   /**

   155    * i18n support

   156    */

   157   TRANSLATIONS : {},

   158   PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; },

   159   LOCALE : 'unknown',

   160 

   161   // gettext and ngettext don't access this so that the functions

   162   // can safely bound to a different name (_ = Documentation.gettext)

   163   gettext : function(string) {

   164     var translated = Documentation.TRANSLATIONS[string];

   165     if (typeof translated === 'undefined')

   166       return string;

   167     return (typeof translated === 'string') ? translated : translated[0];

   168   },

   169 

   170   ngettext : function(singular, plural, n) {

   171     var translated = Documentation.TRANSLATIONS[singular];

   172     if (typeof translated === 'undefined')

   173       return (n == 1) ? singular : plural;

   174     return translated[Documentation.PLURALEXPR(n)];

   175   },

   176 

   177   addTranslations : function(catalog) {

   178     for (var key in catalog.messages)

   179       this.TRANSLATIONS[key] = catalog.messages[key];

   180     this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');

   181     this.LOCALE = catalog.locale;

   182   },

   183 

   184   /**

   185    * add context elements like header anchor links

   186    */

   187   addContextElements : function() {

   188     $('div[id] > :header:first').each(function() {

   189       $('<a class="headerlink">\u00B6</a>').

   190       attr('href', '#' + this.id).

   191       attr('title', _('Permalink to this headline')).

   192       appendTo(this);

   193     });

   194     $('dt[id]').each(function() {

   195       $('<a class="headerlink">\u00B6</a>').

   196       attr('href', '#' + this.id).

   197       attr('title', _('Permalink to this definition')).

   198       appendTo(this);

   199     });

   200   },

   201 

   202   /**

   203    * workaround a firefox stupidity

   204    * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075

   205    */

   206   fixFirefoxAnchorBug : function() {

   207     if (document.location.hash)

   208       window.setTimeout(function() {

   209         document.location.href += '';

   210       }, 10);

   211   },

   212 

   213   /**

   214    * highlight the search words provided in the url in the text

   215    */

   216   highlightSearchWords : function() {

   217     var params = $.getQueryParameters();

   218     var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];

   219     if (terms.length) {

   220       var body = $('div.body');

   221       if (!body.length) {

   222         body = $('body');

   223       }

   224       window.setTimeout(function() {

   225         $.each(terms, function() {

   226           body.highlightText(this.toLowerCase(), 'highlighted');

   227         });

   228       }, 10);

   229       $('<p class="highlight-link"><a href="javascript:Documentation.' +

   230         'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>')

   231           .appendTo($('#searchbox'));

   232     }

   233   },

   234 

   235   /**

   236    * init the domain index toggle buttons

   237    */

   238   initIndexTable : function() {

   239     var togglers = $('img.toggler').click(function() {

   240       var src = $(this).attr('src');

   241       var idnum = $(this).attr('id').substr(7);

   242       $('tr.cg-' + idnum).toggle();

   243       if (src.substr(-9) === 'minus.png')

   244         $(this).attr('src', src.substr(0, src.length-9) + 'plus.png');

   245       else

   246         $(this).attr('src', src.substr(0, src.length-8) + 'minus.png');

   247     }).css('display', '');

   248     if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {

   249         togglers.click();

   250     }

   251   },

   252 

   253   /**

   254    * helper function to hide the search marks again

   255    */

   256   hideSearchWords : function() {

   257     $('#searchbox .highlight-link').fadeOut(300);

   258     $('span.highlighted').removeClass('highlighted');

   259   },

   260 

   261   /**

   262    * make the url absolute

   263    */

   264   makeURL : function(relativeURL) {

   265     return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;

   266   },

   267 

   268   /**

   269    * get the current relative url

   270    */

   271   getCurrentURL : function() {

   272     var path = document.location.pathname;

   273     var parts = path.split(/\//);

   274     $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {

   275       if (this === '..')

   276         parts.pop();

   277     });

   278     var url = parts.join('/');

   279     return path.substring(url.lastIndexOf('/') + 1, path.length - 1);

   280   },

   281 

   282   initOnKeyListeners: function() {

   283     $(document).keyup(function(event) {

   284       var activeElementType = document.activeElement.tagName;

   285       // don't navigate when in search box or textarea

   286       if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT') {

   287         switch (event.keyCode) {

   288           case 37: // left

   289             var prevHref = $('link[rel="prev"]').prop('href');

   290             if (prevHref) {

   291               window.location.href = prevHref;

   292               return false;

   293             }

   294           case 39: // right

   295             var nextHref = $('link[rel="next"]').prop('href');

   296             if (nextHref) {

   297               window.location.href = nextHref;

   298               return false;

   299             }

   300         }

   301       }

   302     });

   303   }

   304 };

   305 

   306 // quick alias for translations

   307 _ = Documentation.gettext;

   308 

   309 $(document).ready(function() {

   310   Documentation.init();

   311 });