1 /*

     2  * doctools.js

     3  * ~~~~~~~~~~~

     4  *

     5  * Sphinx JavaScript utilities for all documentation.

     6  *

     7  * :copyright: Copyright 2007-2014 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) {

    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 = document.createElement("span");

    75         span.className = className;

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

    77         node.parentNode.insertBefore(span, node.parentNode.insertBefore(

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

    79           node.nextSibling));

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

    81       }

    82     }

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

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

    85         highlight(this);

    86       });

    87     }

    88   }

    89   return this.each(function() {

    90     highlight(this);

    91   });

    92 };

    93 

    94 /**

    95  * Small JavaScript module for the documentation.

    96  */

    97 var Documentation = {

    98 

    99   init : function() {

   100     this.fixFirefoxAnchorBug();

   101     this.highlightSearchWords();

   102     this.initIndexTable();

   103   },

   104 

   105   /**

   106    * i18n support

   107    */

   108   TRANSLATIONS : {},

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

   110   LOCALE : 'unknown',

   111 

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

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

   114   gettext : function(string) {

   115     var translated = Documentation.TRANSLATIONS[string];

   116     if (typeof translated == 'undefined')

   117       return string;

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

   119   },

   120 

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

   122     var translated = Documentation.TRANSLATIONS[singular];

   123     if (typeof translated == 'undefined')

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

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

   126   },

   127 

   128   addTranslations : function(catalog) {

   129     for (var key in catalog.messages)

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

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

   132     this.LOCALE = catalog.locale;

   133   },

   134 

   135   /**

   136    * add context elements like header anchor links

   137    */

   138   addContextElements : function() {

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

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

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

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

   143       appendTo(this);

   144     });

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

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

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

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

   149       appendTo(this);

   150     });

   151   },

   152 

   153   /**

   154    * workaround a firefox stupidity

   155    */

   156   fixFirefoxAnchorBug : function() {

   157     if (document.location.hash && $.browser.mozilla)

   158       window.setTimeout(function() {

   159         document.location.href += '';

   160       }, 10);

   161   },

   162 

   163   /**

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

   165    */

   166   highlightSearchWords : function() {

   167     var params = $.getQueryParameters();

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

   169     if (terms.length) {

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

   171       if (!body.length) {

   172         body = $('body');

   173       }

   174       window.setTimeout(function() {

   175         $.each(terms, function() {

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

   177         });

   178       }, 10);

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

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

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

   182     }

   183   },

   184 

   185   /**

   186    * init the domain index toggle buttons

   187    */

   188   initIndexTable : function() {

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

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

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

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

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

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

   195       else

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

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

   198     if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {

   199         togglers.click();

   200     }

   201   },

   202 

   203   /**

   204    * helper function to hide the search marks again

   205    */

   206   hideSearchWords : function() {

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

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

   209   },

   210 

   211   /**

   212    * make the url absolute

   213    */

   214   makeURL : function(relativeURL) {

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

   216   },

   217 

   218   /**

   219    * get the current relative url

   220    */

   221   getCurrentURL : function() {

   222     var path = document.location.pathname;

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

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

   225       if (this == '..')

   226         parts.pop();

   227     });

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

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

   230   }

   231 };

   232 

   233 // quick alias for translations

   234 _ = Documentation.gettext;

   235 

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

   237   Documentation.init();

   238 });