Simplified doc-site generationjellyfish_9.99.4jellyfish/9.99.49.99.4

Updated theme to windmill Using Mkdocs static site generator Deployed on readthedocs

Signed-off-by: growupboron <shankhoghosh123@gmail.com>
Change-Id: If62eaaea1855c91b64f687900f54eba6bc1caee8
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/25236
Reviewed-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Tested-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>

1 files changed, 568 insertions, 0 deletions

diff --git a/theme/mkdocs_windmill/js/base.js b/theme/mkdocs_windmill/js/base.js
new file mode 100644
index 0000000..51d5b5e
--- /dev/null
+++ b/theme/mkdocs_windmill/js/base.js
@@ -0,0 +1,568 @@
+/* global window, document, $, hljs, elasticlunr, base_url, is_top_frame */
+/* exported getParam, onIframeLoad */
+"use strict";
+
+// The full page consists of a main window with navigation and table of contents, and an inner
+// iframe containing the current article. Which article is shown is determined by the main
+// window's #hash portion of the URL. In fact, we use the simple rule: main window's URL of
+// "rootUrl#relPath" corresponds to iframe's URL of "rootUrl/relPath".
+//
+// The main frame and the contents of the index page actually live in a single generated html
+// file: the outer frame hides one half, and the inner hides the other. TODO: this should be
+// possible to greatly simplify after mkdocs-1.0 release.
+
+var mainWindow = is_top_frame ? window : (window.parent !== window ? window.parent : null);
+var iframeWindow = null;
+var rootUrl = qualifyUrl(base_url);
+var searchIndex = null;
+var showPageToc = true;
+var MutationObserver = window.MutationObserver || window.WebKitMutationObserver;
+
+var Keys = {
+  ENTER:  13,
+  ESCAPE: 27,
+  UP:     38,
+  DOWN:   40,
+};
+
+function startsWith(str, prefix) { return str.lastIndexOf(prefix, 0) === 0; }
+function endsWith(str, suffix) { return str.indexOf(suffix, str.length - suffix.length) !== -1; }
+
+/**
+ * Returns whether to use small-screen mode. Note that the same size is used in css @media block.
+ */
+function isSmallScreen() {
+  return window.matchMedia("(max-width: 600px)").matches;
+}
+
+/**
+ * Given a relative URL, returns the absolute one, relying on the browser to convert it.
+ */
+function qualifyUrl(url) {
+  var a = document.createElement('a');
+  a.href = url;
+  return a.href;
+}
+
+/**
+ * Turns an absolute path to relative, stripping out rootUrl + separator.
+ */
+function getRelPath(separator, absUrl) {
+  var prefix = rootUrl + (endsWith(rootUrl, separator) ? '' : separator);
+  return startsWith(absUrl, prefix) ? absUrl.slice(prefix.length) : null;
+}
+
+/**
+ * Turns a relative path to absolute, adding a prefix of rootUrl + separator.
+ */
+function getAbsUrl(separator, relPath) {
+  var sep = endsWith(rootUrl, separator) ? '' : separator;
+  return relPath === null ? null : rootUrl + sep + relPath;
+}
+
+/**
+ * Redirects the iframe to reflect the path represented by the main window's current URL.
+ * (In our design, nothing should change iframe's src except via updateIframe(), or back/forward
+ * history is likely to get messed up.)
+ */
+function updateIframe(enableForwardNav) {
+  // Grey out the "forward" button if we don't expect 'forward' to work.
+  $('#hist-fwd').toggleClass('greybtn', !enableForwardNav);
+
+  var targetRelPath = getRelPath('#', mainWindow.location.href) || '';
+  var targetIframeUrl = getAbsUrl('/', targetRelPath);
+  var loc = iframeWindow.location;
+  var currentIframeUrl = _safeGetLocationHref(loc);
+
+  console.log("updateIframe: %s -> %s (%s)", currentIframeUrl, targetIframeUrl,
+    currentIframeUrl === targetIframeUrl ? "same" : "replacing");
+
+  if (currentIframeUrl !== targetIframeUrl) {
+    loc.replace(targetIframeUrl);
+    onIframeBeforeLoad(targetIframeUrl);
+  }
+  document.body.scrollTop = 0;
+}
+
+/**
+ * Returns location.href, catching exception that's triggered if the iframe is on a different domain.
+ */
+function _safeGetLocationHref(location) {
+  try {
+    return location.href;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Returns the value of the given parameter in the URL's query portion.
+ */
+function getParam(key) {
+  var params = window.location.search.substring(1).split('&');
+  for (var i = 0; i < params.length; i++) {
+    var param = params[i].split('=');
+    if (param[0] === key) {
+      return decodeURIComponent(param[1].replace(/\+/g, '%20'));
+    }
+  }
+}
+
+/**
+ * Update the state of the button toggling table-of-contents. TOC has different behavior
+ * depending on screen size, so the button's behavior depends on that too.
+ */
+function updateTocButtonState() {
+  var shown;
+  if (isSmallScreen()) {
+    shown = $('.wm-toc-pane').hasClass('wm-toc-dropdown');
+  } else {
+    shown = !$('#main-content').hasClass('wm-toc-hidden');
+  }
+  $('#wm-toc-button').toggleClass('active', shown);
+}
+
+/**
+ * Update the height of the iframe container. On small screens, we adjust it to fit the iframe
+ * contents, so that the page scrolls as a whole rather than inside the iframe.
+ */
+function updateContentHeight() {
+  if (isSmallScreen()) {
+    $('.wm-content-pane').height(iframeWindow.document.body.offsetHeight + 20);
+    $('.wm-article').attr('scrolling', 'no');
+  } else {
+    $('.wm-content-pane').height('');
+    $('.wm-article').attr('scrolling', 'auto');
+  }
+}
+
+/**
+ * When TOC is a dropdown (on small screens), close it.
+ */
+function closeTempItems() {
+  $('.wm-toc-dropdown').removeClass('wm-toc-dropdown');
+  $('#mkdocs-search-query').closest('.wm-top-tool').removeClass('wm-top-tool-expanded');
+  updateTocButtonState();
+}
+
+/**
+ * Visit the given URL. This changes the hash of the top page to reflect the new URL's relative
+ * path, and points the iframe to the new URL.
+ */
+function visitUrl(url, event) {
+  var relPath = getRelPath('/', url);
+  if (relPath !== null) {
+    event.preventDefault();
+    var newUrl = getAbsUrl('#', relPath);
+    if (newUrl !== mainWindow.location.href) {
+      mainWindow.history.pushState(null, '', newUrl);
+      updateIframe(false);
+    }
+    closeTempItems();
+    iframeWindow.focus();
+  }
+}
+
+/**
+ * Adjusts link to point to a top page, converting URL from "base/path" to "base#path". It also
+ * sets a data-adjusted attribute on the link, to skip adjustments on future clicks.
+ */
+function adjustLink(linkEl) {
+  if (!linkEl.hasAttribute('data-wm-adjusted')) {
+    linkEl.setAttribute('data-wm-adjusted', 'done');
+    var relPath = getRelPath('/', linkEl.href);
+    if (relPath !== null) {
+      var newUrl = getAbsUrl('#', relPath);
+      linkEl.href = newUrl;
+    }
+  }
+}
+
+/**
+ * Given a URL, strips query and fragment, returning just the path.
+ */
+function cleanUrlPath(relUrl) {
+  return relUrl.replace(/[#?].*/, '');
+}
+
+/**
+ * Initialize the main window.
+ */
+function initMainWindow() {
+  // wm-toc-button either opens the table of contents in the side-pane, or (on smaller screens)
+  // shows the side-pane as a drop-down.
+  $('#wm-toc-button').on('click', function(e) {
+    if (isSmallScreen()) {
+      $('.wm-toc-pane').toggleClass('wm-toc-dropdown');
+      $('#wm-main-content').removeClass('wm-toc-hidden');
+    } else {
+      $('#main-content').toggleClass('wm-toc-hidden');
+      closeTempItems();
+    }
+    updateTocButtonState();
+  });
+
+  // Update the state of the wm-toc-button
+  updateTocButtonState();
+  $(window).on('resize', function() {
+    updateTocButtonState();
+    updateContentHeight();
+  });
+
+  // Connect up the Back and Forward buttons (if present).
+  $('#hist-back').on('click', function(e) { window.history.back(); });
+  $('#hist-fwd').on('click', function(e) { window.history.forward(); });
+
+  // When the side-pane is a dropdown, hide it on click-away.
+  $(window).on('blur', closeTempItems);
+
+  // When we click on an opener in the table of contents, open it.
+  $('.wm-toc-pane').on('click', '.wm-toc-opener', function(e) {
+    $(this).toggleClass('wm-toc-open');
+    $(this).next('.wm-toc-li-nested').collapse('toggle');
+  });
+  $('.wm-toc-pane').on('click', '.wm-page-toc-opener', function(e) {
+    // Ignore clicks while transitioning.
+    if ($(this).next('.wm-page-toc').hasClass('collapsing')) { return; }
+    showPageToc = !showPageToc;
+    $(this).toggleClass('wm-page-toc-open', showPageToc);
+    $(this).next('.wm-page-toc').collapse(showPageToc ? 'show' : 'hide');
+  });
+
+  // Once the article loads in the side-pane, close the dropdown.
+  $('.wm-article').on('load', function() {
+    document.title = iframeWindow.document.title;
+    updateContentHeight();
+
+    // We want to update content height whenever the height of the iframe's content changes.
+    // Using MutationObserver seems to be the best way to do that.
+    var observer = new MutationObserver(updateContentHeight);
+    observer.observe(iframeWindow.document.body, {
+      attributes: true,
+      childList: true,
+      characterData: true,
+      subtree: true
+    });
+
+    iframeWindow.focus();
+  });
+
+  // Initialize search functionality.
+  initSearch();
+
+  // Load the iframe now, and whenever we navigate the top frame.
+  setTimeout(function() { updateIframe(false); }, 0);
+  // For our usage, 'popstate' or 'hashchange' would work, but only 'hashchange' work on IE.
+  $(window).on('hashchange', function() { updateIframe(true); });
+}
+
+function onIframeBeforeLoad(url) {
+  $('.wm-current').removeClass('wm-current');
+  closeTempItems();
+
+  var tocLi = getTocLi(url);
+  tocLi.addClass('wm-current');
+  tocLi.parents('.wm-toc-li-nested')
+    // It's better to open parent items immediately without a transition.
+    .removeClass('collapsing').addClass('collapse in').height('')
+    .prev('.wm-toc-opener').addClass('wm-toc-open');
+}
+
+function getTocLi(url) {
+  var relPath = getAbsUrl('#', getRelPath('/', cleanUrlPath(url)));
+  var selector = '.wm-article-link[href="' + relPath + '"]';
+  return $(selector).closest('.wm-toc-li');
+}
+
+var _deferIframeLoad = false;
+
+// Sometimes iframe is loaded before main window's ready callback. In this case, we defer
+// onIframeLoad call until the main window has initialized.
+function ensureIframeLoaded() {
+  if (_deferIframeLoad) {
+    onIframeLoad();
+  }
+}
+
+function onIframeLoad() {
+  if (!iframeWindow) { _deferIframeLoad = true; return; }
+  var url = iframeWindow.location.href;
+  onIframeBeforeLoad(url);
+
+  if (iframeWindow.pageToc) {
+    var relPath = getAbsUrl('#', getRelPath('/', cleanUrlPath(url)));
+    renderPageToc(getTocLi(url), relPath, iframeWindow.pageToc);
+  }
+  iframeWindow.focus();
+}
+
+/**
+ * Hides a bootstrap collapsible element, and removes it from DOM once hidden.
+ */
+function collapseAndRemove(collapsibleElem) {
+  if (!collapsibleElem.hasClass('in')) {
+    // If the element is already hidden, just remove it immediately.
+    collapsibleElem.remove();
+  } else {
+    collapsibleElem.on('hidden.bs.collapse', function() {
+      collapsibleElem.remove();
+    })
+    .collapse('hide');
+  }
+}
+
+function renderPageToc(parentElem, pageUrl, pageToc) {
+  var ul = $('<ul class="wm-toctree">');
+  function addItem(tocItem) {
+    ul.append($('<li class="wm-toc-li">')
+      .append($('<a class="wm-article-link wm-page-toc-text">')
+        .attr('href', pageUrl + tocItem.url)
+        .attr('data-wm-adjusted', 'done')
+        .text(tocItem.title)));
+    if (tocItem.children) {
+      tocItem.children.forEach(addItem);
+    }
+  }
+  pageToc.forEach(addItem);
+
+  $('.wm-page-toc-opener').removeClass('wm-page-toc-opener wm-page-toc-open');
+  collapseAndRemove($('.wm-page-toc'));
+
+  parentElem.addClass('wm-page-toc-opener').toggleClass('wm-page-toc-open', showPageToc);
+  $('<li class="wm-page-toc wm-toc-li-nested collapse">').append(ul).insertAfter(parentElem)
+    .collapse(showPageToc ? 'show' : 'hide');
+}
+
+
+if (!mainWindow) {
+  // This is a page that ought to be in an iframe. Redirect to load the top page instead.
+  var topUrl = getAbsUrl('#', getRelPath('/', window.location.href));
+  if (topUrl) {
+    window.location.href = topUrl;
+  }
+
+} else {
+  // Adjust all links to point to the top page with the right hash fragment.
+  $(document).ready(function() {
+    $('a').each(function() { adjustLink(this); });
+  });
+
+  // For any dynamically-created links, adjust them on click.
+  $(document).on('click', 'a:not([data-wm-adjusted])', function(e) { adjustLink(this); });
+}
+
+if (is_top_frame) {
+  // Main window.
+  $(document).ready(function() {
+    iframeWindow = $('.wm-article')[0].contentWindow;
+    initMainWindow();
+    ensureIframeLoaded();
+  });
+
+} else {
+  // Article contents.
+  iframeWindow = window;
+  if (mainWindow) {
+    mainWindow.onIframeLoad();
+  }
+
+  // Other initialization of iframe contents.
+  hljs.initHighlightingOnLoad();
+  $(document).ready(function() {
+    $('table').addClass('table table-striped table-hover table-bordered table-condensed');
+  });
+}
+
+
+var searchIndexReady = false;
+
+/**
+ * Initialize search functionality.
+ */
+function initSearch() {
+  // Create elasticlunr index.
+  searchIndex = elasticlunr(function() {
+    this.setRef('location');
+    this.addField('title');
+    this.addField('text');
+  });
+
+  var searchBox = $('#mkdocs-search-query');
+  var searchResults = $('#mkdocs-search-results');
+
+  // Fetch the prebuilt index data, and add to the index.
+  $.getJSON(base_url + '/search/search_index.json')
+  .done(function(data) {
+    data.docs.forEach(function(doc) {
+      searchIndex.addDoc(doc);
+    });
+    searchIndexReady = true;
+    $(document).trigger('searchIndexReady');
+  });
+
+  function showSearchResults(optShow) {
+    var show = (optShow === false ? false : Boolean(searchBox.val()));
+    if (show) {
+      doSearch({
+        resultsElem: searchResults,
+        query: searchBox.val(),
+        snippetLen: 100,
+        limit: 10
+      });
+    }
+    searchResults.parent().toggleClass('open', show);
+    return show;
+  }
+
+  searchBox.on('click', function(e) {
+    if (!searchResults.parent().hasClass('open')) {
+      if (showSearchResults()) {
+        e.stopPropagation();
+      }
+    }
+  });
+
+  // Search automatically and show results on keyup event.
+  searchBox.on('keyup', function(e) {
+    var show = (e.which !== Keys.ESCAPE && e.which !== Keys.ENTER);
+    showSearchResults(show);
+  });
+
+  // Open the search box (and run the search) on up/down arrow keys.
+  searchBox.on('keydown', function(e) {
+    if (e.which === Keys.UP || e.which === Keys.DOWN) {
+      if (showSearchResults()) {
+        e.stopPropagation();
+        e.preventDefault();
+        setTimeout(function() {
+          searchResults.find('a').eq(e.which === Keys.UP ? -1 : 0).focus();
+        }, 0);
+      }
+    }
+  });
+
+  searchResults.on('keydown', function(e) {
+    if (e.which === Keys.UP || e.which === Keys.DOWN) {
+      if (searchResults.find('a').eq(e.which === Keys.UP ? 0 : -1)[0] === e.target) {
+        searchBox.focus();
+        e.stopPropagation();
+        e.preventDefault();
+      }
+    }
+  });
+
+  $(searchResults).on('click', '.search-all', function(e) {
+    e.stopPropagation();
+    e.preventDefault();
+    $('#wm-search-form').trigger('submit');
+  });
+
+  // Redirect to the search page on Enter or button-click (form submit).
+  $('#wm-search-form').on('submit', function(e) {
+    var url = this.action + '?' + $(this).serialize();
+    visitUrl(url, e);
+    searchResults.parent().removeClass('open');
+  });
+
+  $('#wm-search-show,#wm-search-go').on('click', function(e) {
+    if (isSmallScreen()) {
+      e.preventDefault();
+      var el = $('#mkdocs-search-query').closest('.wm-top-tool');
+      el.toggleClass('wm-top-tool-expanded');
+      if (el.hasClass('wm-top-tool-expanded')) {
+        setTimeout(function() {
+          $('#mkdocs-search-query').focus();
+          showSearchResults();
+        }, 0);
+        $('#mkdocs-search-query').focus();
+      }
+    }
+  });
+}
+
+function escapeRegex(s) {
+  return s.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
+}
+
+/**
+ * This helps construct useful snippets to show in search results, and highlight matches.
+ */
+function SnippetBuilder(query) {
+  var termsPattern = elasticlunr.tokenizer(query).map(escapeRegex).join("|");
+  this._termsRegex = termsPattern ? new RegExp(termsPattern, "gi") : null;
+}
+
+SnippetBuilder.prototype.getSnippet = function(text, len) {
+  if (!this._termsRegex) {
+    return text.slice(0, len);
+  }
+
+  // Find a position that includes something we searched for.
+  var pos = text.search(this._termsRegex);
+  if (pos < 0) { pos = 0; }
+
+  // Find a period before that position (a good starting point).
+  var start = text.lastIndexOf('.', pos) + 1;
+  if (pos - start > 30) {
+    // If too long to previous period, give it 30 characters, and find a space before that.
+    start = text.lastIndexOf(' ', pos - 30) + 1;
+  }
+  var rawSnippet = text.slice(start, start + len);
+  return rawSnippet.replace(this._termsRegex, '<b>$&</b>');
+};
+
+/**
+ * Search the elasticlunr index for the given query, and populate the dropdown with results.
+ */
+function doSearch(options) {
+  var resultsElem = options.resultsElem;
+  resultsElem.empty();
+
+  // If the index isn't ready, wait for it, and search again when ready.
+  if (!searchIndexReady) {
+    resultsElem.append($('<li class="disabled"><a class="search-link">SEARCHING...</a></li>'));
+    $(document).one('searchIndexReady', function() { doSearch(options); });
+    return;
+  }
+
+  var query = options.query;
+  var snippetLen = options.snippetLen;
+  var limit = options.limit;
+
+  if (query === '') { return; }
+
+  var results = searchIndex.search(query, {
+    fields: { title: {boost: 10}, text: { boost: 1 } },
+    expand: true,
+    bool: "AND"
+  });
+
+  var snippetBuilder = new SnippetBuilder(query);
+  if (results.length > 0){
+    var len = Math.min(results.length, limit || Infinity);
+    for (var i = 0; i < len; i++) {
+      var doc = searchIndex.documentStore.getDoc(results[i].ref);
+      var snippet = snippetBuilder.getSnippet(doc.text, snippetLen);
+      resultsElem.append(
+        $('<li>').append($('<a class="search-link">').attr('href', pathJoin(base_url, doc.location))
+          .append($('<div class="search-title">').text(doc.title))
+          .append($('<div class="search-text">').html(snippet)))
+      );
+    }
+    resultsElem.find('a').each(function() { adjustLink(this); });
+    if (limit) {
+      resultsElem.append($('<li role="separator" class="divider"></li>'));
+      resultsElem.append($(
+        '<li><a class="search-link search-all" href="' + base_url + '/search.html">' +
+        '<div class="search-title">SEE ALL RESULTS</div></a></li>'));
+    }
+  } else {
+    resultsElem.append($('<li class="disabled"><a class="search-link">NO RESULTS FOUND</a></li>'));
+  }
+}
+
+function pathJoin(prefix, suffix) {
+  var nPrefix = endsWith(prefix, "/") ? prefix.slice(0, -1) : prefix;
+  var nSuffix = startsWith(suffix, "/") ? suffix.slice(1) : suffix;
+  return nPrefix + "/" + nSuffix;
+}