Deploying to docs from @ python-discord/bot-core@c7a6ddd00eb371759d837aa75fa397c6d5771401 🚀

5 files changed, 233 insertions, 165 deletions

diff --git a/v8.0.0/_static/basic.css b/v8.0.0/_static/basic.css
index 4e9a9f1f..eeb0519a 100644
--- a/v8.0.0/_static/basic.css
+++ b/v8.0.0/_static/basic.css
@@ -236,6 +236,16 @@ div.body p, div.body dd, div.body li, div.body blockquote {
 a.headerlink {
     visibility: hidden;
 }
+a.brackets:before,
+span.brackets > a:before{
+    content: "[";
+}
+
+a.brackets:after,
+span.brackets > a:after {
+    content: "]";
+}
+
 
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
@@ -324,15 +334,11 @@ aside.sidebar {
 p.sidebar-title {
     font-weight: bold;
 }
-nav.contents,
-aside.topic,
 div.admonition, div.topic, blockquote {
     clear: left;
 }
 
 /* -- topics ---------------------------------------------------------------- */
-nav.contents,
-aside.topic,
 div.topic {
     border: 1px solid #ccc;
     padding: 7px;
@@ -371,8 +377,6 @@ div.body p.centered {
 
 div.sidebar > :last-child,
 aside.sidebar > :last-child,
-nav.contents > :last-child,
-aside.topic > :last-child,
 div.topic > :last-child,
 div.admonition > :last-child {
     margin-bottom: 0;
@@ -380,8 +384,6 @@ div.admonition > :last-child {
 
 div.sidebar::after,
 aside.sidebar::after,
-nav.contents::after,
-aside.topic::after,
 div.topic::after,
 div.admonition::after,
 blockquote::after {
@@ -606,26 +608,19 @@ ol.simple p,
 ul.simple p {
     margin-bottom: 0;
 }
-aside.footnote > span,
-div.citation > span {
+dl.footnote > dt,
+dl.citation > dt {
     float: left;
+    margin-right: 0.5em;
 }
-aside.footnote > span:last-of-type,
-div.citation > span:last-of-type {
-  padding-right: 0.5em;
-}
-aside.footnote > p {
-  margin-left: 2em;
-}
-div.citation > p {
-  margin-left: 4em;
-}
-aside.footnote > p:last-of-type,
-div.citation > p:last-of-type {
+
+dl.footnote > dd,
+dl.citation > dd {
     margin-bottom: 0em;
 }
-aside.footnote > p:last-of-type:after,
-div.citation > p:last-of-type:after {
+
+dl.footnote > dd:after,
+dl.citation > dd:after {
     content: "";
     clear: both;
 }
@@ -641,6 +636,10 @@ dl.field-list > dt {
     padding-left: 0.5em;
     padding-right: 5px;
 }
+dl.field-list > dt:after {
+    content: ":";
+}
+
 
 dl.field-list > dd {
     padding-left: 0.5em;
diff --git a/v8.0.0/_static/doctools.js b/v8.0.0/_static/doctools.js
index c3db08d1..527b876c 100644
--- a/v8.0.0/_static/doctools.js
+++ b/v8.0.0/_static/doctools.js
@@ -10,6 +10,13 @@
  */
 "use strict";
 
+const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
+  "TEXTAREA",
+  "INPUT",
+  "SELECT",
+  "BUTTON",
+]);
+
 const _ready = (callback) => {
   if (document.readyState !== "loading") {
     callback();
@@ -19,72 +26,10 @@ const _ready = (callback) => {
 };
 
 /**
- * highlight a given string on a node by wrapping it in
- * span elements with the given class name.
- */
-const _highlight = (node, addItems, text, className) => {
-  if (node.nodeType === Node.TEXT_NODE) {
-    const val = node.nodeValue;
-    const parent = node.parentNode;
-    const pos = val.toLowerCase().indexOf(text);
-    if (
-      pos >= 0 &&
-      !parent.classList.contains(className) &&
-      !parent.classList.contains("nohighlight")
-    ) {
-      let span;
-
-      const closestNode = parent.closest("body, svg, foreignObject");
-      const isInSVG = closestNode && closestNode.matches("svg");
-      if (isInSVG) {
-        span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
-      } else {
-        span = document.createElement("span");
-        span.classList.add(className);
-      }
-
-      span.appendChild(document.createTextNode(val.substr(pos, text.length)));
-      parent.insertBefore(
-        span,
-        parent.insertBefore(
-          document.createTextNode(val.substr(pos + text.length)),
-          node.nextSibling
-        )
-      );
-      node.nodeValue = val.substr(0, pos);
-
-      if (isInSVG) {
-        const rect = document.createElementNS(
-          "http://www.w3.org/2000/svg",
-          "rect"
-        );
-        const bbox = parent.getBBox();
-        rect.x.baseVal.value = bbox.x;
-        rect.y.baseVal.value = bbox.y;
-        rect.width.baseVal.value = bbox.width;
-        rect.height.baseVal.value = bbox.height;
-        rect.setAttribute("class", className);
-        addItems.push({ parent: parent, target: rect });
-      }
-    }
-  } else if (node.matches && !node.matches("button, select, textarea")) {
-    node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
-  }
-};
-const _highlightText = (thisNode, text, className) => {
-  let addItems = [];
-  _highlight(thisNode, addItems, text, className);
-  addItems.forEach((obj) =>
-    obj.parent.insertAdjacentElement("beforebegin", obj.target)
-  );
-};
-
-/**
  * Small JavaScript module for the documentation.
  */
 const Documentation = {
   init: () => {
-    Documentation.highlightSearchWords();
     Documentation.initDomainIndexTable();
     Documentation.initOnKeyListeners();
   },
@@ -127,51 +72,6 @@ const Documentation = {
   },
 
   /**
-   * highlight the search words provided in the url in the text
-   */
-  highlightSearchWords: () => {
-    const highlight =
-      new URLSearchParams(window.location.search).get("highlight") || "";
-    const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
-    if (terms.length === 0) return; // nothing to do
-
-    // There should never be more than one element matching "div.body"
-    const divBody = document.querySelectorAll("div.body");
-    const body = divBody.length ? divBody[0] : document.querySelector("body");
-    window.setTimeout(() => {
-      terms.forEach((term) => _highlightText(body, term, "highlighted"));
-    }, 10);
-
-    const searchBox = document.getElementById("searchbox");
-    if (searchBox === null) return;
-    searchBox.appendChild(
-      document
-        .createRange()
-        .createContextualFragment(
-          '<p class="highlight-link">' +
-            '<a href="javascript:Documentation.hideSearchWords()">' +
-            Documentation.gettext("Hide Search Matches") +
-            "</a></p>"
-        )
-    );
-  },
-
-  /**
-   * helper function to hide the search marks again
-   */
-  hideSearchWords: () => {
-    document
-      .querySelectorAll("#searchbox .highlight-link")
-      .forEach((el) => el.remove());
-    document
-      .querySelectorAll("span.highlighted")
-      .forEach((el) => el.classList.remove("highlighted"));
-    const url = new URL(window.location);
-    url.searchParams.delete("highlight");
-    window.history.replaceState({}, "", url);
-  },
-
-  /**
    * helper function to focus on search bar
    */
   focusSearchBar: () => {
@@ -210,15 +110,11 @@ const Documentation = {
     )
       return;
 
-    const blacklistedElements = new Set([
-      "TEXTAREA",
-      "INPUT",
-      "SELECT",
-      "BUTTON",
-    ]);
     document.addEventListener("keydown", (event) => {
-      if (blacklistedElements.has(document.activeElement.tagName)) return; // bail for input elements
-      if (event.altKey || event.ctrlKey || event.metaKey) return; // bail with special keys
+      // bail for input elements
+      if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
+      // bail with special keys
+      if (event.altKey || event.ctrlKey || event.metaKey) return;
 
       if (!event.shiftKey) {
         switch (event.key) {
@@ -240,10 +136,6 @@ const Documentation = {
               event.preventDefault();
             }
             break;
-          case "Escape":
-            if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
-            Documentation.hideSearchWords();
-            event.preventDefault();
         }
       }
 
diff --git a/v8.0.0/_static/pygments.css b/v8.0.0/_static/pygments.css
index 75471509..053cfd3d 100644
--- a/v8.0.0/_static/pygments.css
+++ b/v8.0.0/_static/pygments.css
@@ -54,7 +54,6 @@
 .highlight .nt { color: #204a87; font-weight: bold } /* Name.Tag */
 .highlight .nv { color: #000000 } /* Name.Variable */
 .highlight .ow { color: #204a87; font-weight: bold } /* Operator.Word */
-.highlight .pm { color: #000000; font-weight: bold } /* Punctuation.Marker */
 .highlight .w { color: #f8f8f8 } /* Text.Whitespace */
 .highlight .mb { color: #0000cf; font-weight: bold } /* Literal.Number.Bin */
 .highlight .mf { color: #0000cf; font-weight: bold } /* Literal.Number.Float */
@@ -139,7 +138,6 @@ body[data-theme="dark"] .highlight .py { color: #d0d0d0 } /* Name.Property */
 body[data-theme="dark"] .highlight .nt { color: #6ebf26; font-weight: bold } /* Name.Tag */
 body[data-theme="dark"] .highlight .nv { color: #40ffff } /* Name.Variable */
 body[data-theme="dark"] .highlight .ow { color: #6ebf26; font-weight: bold } /* Operator.Word */
-body[data-theme="dark"] .highlight .pm { color: #d0d0d0 } /* Punctuation.Marker */
 body[data-theme="dark"] .highlight .w { color: #666666 } /* Text.Whitespace */
 body[data-theme="dark"] .highlight .mb { color: #51b2fd } /* Literal.Number.Bin */
 body[data-theme="dark"] .highlight .mf { color: #51b2fd } /* Literal.Number.Float */
@@ -224,7 +222,6 @@ body:not([data-theme="light"]) .highlight .py { color: #d0d0d0 } /* Name.Propert
 body:not([data-theme="light"]) .highlight .nt { color: #6ebf26; font-weight: bold } /* Name.Tag */
 body:not([data-theme="light"]) .highlight .nv { color: #40ffff } /* Name.Variable */
 body:not([data-theme="light"]) .highlight .ow { color: #6ebf26; font-weight: bold } /* Operator.Word */
-body:not([data-theme="light"]) .highlight .pm { color: #d0d0d0 } /* Punctuation.Marker */
 body:not([data-theme="light"]) .highlight .w { color: #666666 } /* Text.Whitespace */
 body:not([data-theme="light"]) .highlight .mb { color: #51b2fd } /* Literal.Number.Bin */
 body:not([data-theme="light"]) .highlight .mf { color: #51b2fd } /* Literal.Number.Float */
diff --git a/v8.0.0/_static/searchtools.js b/v8.0.0/_static/searchtools.js
index f2fb7d5c..e89e34d4 100644
--- a/v8.0.0/_static/searchtools.js
+++ b/v8.0.0/_static/searchtools.js
@@ -57,14 +57,14 @@ const _removeChildren = (element) => {
 const _escapeRegExp = (string) =>
   string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
 
-const _displayItem = (item, highlightTerms, searchTerms) => {
+const _displayItem = (item, searchTerms) => {
   const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
   const docUrlRoot = DOCUMENTATION_OPTIONS.URL_ROOT;
   const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
   const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
   const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
 
-  const [docName, title, anchor, descr] = item;
+  const [docName, title, anchor, descr, score, _filename] = item;
 
   let listItem = document.createElement("li");
   let requestUrl;
@@ -82,10 +82,9 @@ const _displayItem = (item, highlightTerms, searchTerms) => {
     requestUrl = docUrlRoot + docName + docFileSuffix;
     linkUrl = docName + docLinkSuffix;
   }
-  const params = new URLSearchParams();
-  params.set("highlight", [...highlightTerms].join(" "));
   let linkEl = listItem.appendChild(document.createElement("a"));
-  linkEl.href = linkUrl + "?" + params.toString() + anchor;
+  linkEl.href = linkUrl + anchor;
+  linkEl.dataset.score = score;
   linkEl.innerHTML = title;
   if (descr)
     listItem.appendChild(document.createElement("span")).innerHTML =
@@ -96,7 +95,7 @@ const _displayItem = (item, highlightTerms, searchTerms) => {
       .then((data) => {
         if (data)
           listItem.appendChild(
-            Search.makeSearchSummary(data, searchTerms, highlightTerms)
+            Search.makeSearchSummary(data, searchTerms)
           );
       });
   Search.output.appendChild(listItem);
@@ -116,15 +115,14 @@ const _finishSearch = (resultCount) => {
 const _displayNextItem = (
   results,
   resultCount,
-  highlightTerms,
   searchTerms
 ) => {
   // results left, load the summary and display it
   // this is intended to be dynamic (don't sub resultsCount)
   if (results.length) {
-    _displayItem(results.pop(), highlightTerms, searchTerms);
+    _displayItem(results.pop(), searchTerms);
     setTimeout(
-      () => _displayNextItem(results, resultCount, highlightTerms, searchTerms),
+      () => _displayNextItem(results, resultCount, searchTerms),
       5
     );
   }
@@ -237,6 +235,12 @@ const Search = {
    * execute search (requires search index to be loaded)
    */
   query: (query) => {
+    const filenames = Search._index.filenames;
+    const docNames = Search._index.docnames;
+    const titles = Search._index.titles;
+    const allTitles = Search._index.alltitles;
+    const indexEntries = Search._index.indexentries;
+
     // stem the search terms and add them to the correct list
     const stemmer = new Stemmer();
     const searchTerms = new Set();
@@ -264,6 +268,10 @@ const Search = {
       }
     });
 
+    if (SPHINX_HIGHLIGHT_ENABLED) {  // set in sphinx_highlight.js
+      localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" "))
+    }
+
     // console.debug("SEARCH: searching for:");
     // console.info("required: ", [...searchTerms]);
     // console.info("excluded: ", [...excludedTerms]);
@@ -272,6 +280,40 @@ const Search = {
     let results = [];
     _removeChildren(document.getElementById("search-progress"));
 
+    const queryLower = query.toLowerCase();
+    for (const [title, foundTitles] of Object.entries(allTitles)) {
+      if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) {
+        for (const [file, id] of foundTitles) {
+          let score = Math.round(100 * queryLower.length / title.length)
+          results.push([
+            docNames[file],
+            titles[file] !== title ? `${titles[file]} > ${title}` : title,
+            id !== null ? "#" + id : "",
+            null,
+            score,
+            filenames[file],
+          ]);
+        }
+      }
+    }
+
+    // search for explicit entries in index directives
+    for (const [entry, foundEntries] of Object.entries(indexEntries)) {
+      if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) {
+        for (const [file, id] of foundEntries) {
+          let score = Math.round(100 * queryLower.length / entry.length)
+          results.push([
+            docNames[file],
+            titles[file],
+            id ? "#" + id : "",
+            null,
+            score,
+            filenames[file],
+          ]);
+        }
+      }
+    }
+
     // lookup as object
     objectTerms.forEach((term) =>
       results.push(...Search.performObjectSearch(term, objectTerms))
@@ -318,7 +360,7 @@ const Search = {
     // console.info("search results:", Search.lastresults);
 
     // print the results
-    _displayNextItem(results, results.length, highlightTerms, searchTerms);
+    _displayNextItem(results, results.length, searchTerms);
   },
 
   /**
@@ -399,8 +441,8 @@ const Search = {
     // prepare search
     const terms = Search._index.terms;
     const titleTerms = Search._index.titleterms;
-    const docNames = Search._index.docnames;
     const filenames = Search._index.filenames;
+    const docNames = Search._index.docnames;
     const titles = Search._index.titles;
 
     const scoreMap = new Map();
@@ -497,11 +539,9 @@ const Search = {
   /**
    * helper function to return a node containing the
    * search summary for a given text. keywords is a list
-   * of stemmed words, highlightWords is the list of normal, unstemmed
-   * words. the first one is used to find the occurrence, the
-   * latter for highlighting it.
+   * of stemmed words.
    */
-  makeSearchSummary: (htmlText, keywords, highlightWords) => {
+  makeSearchSummary: (htmlText, keywords) => {
     const text = Search.htmlToText(htmlText);
     if (text === "") return null;
 
@@ -519,10 +559,6 @@ const Search = {
     summary.classList.add("context");
     summary.textContent = top + text.substr(startWithContext, 240).trim() + tail;
 
-    highlightWords.forEach((highlightWord) =>
-      _highlightText(summary, highlightWord, "highlighted")
-    );
-
     return summary;
   },
 };
diff --git a/v8.0.0/_static/sphinx_highlight.js b/v8.0.0/_static/sphinx_highlight.js
new file mode 100644
index 00000000..aae669d7
--- /dev/null
+++ b/v8.0.0/_static/sphinx_highlight.js
@@ -0,0 +1,144 @@
+/* Highlighting utilities for Sphinx HTML documentation. */
+"use strict";
+
+const SPHINX_HIGHLIGHT_ENABLED = true
+
+/**
+ * highlight a given string on a node by wrapping it in
+ * span elements with the given class name.
+ */
+const _highlight = (node, addItems, text, className) => {
+  if (node.nodeType === Node.TEXT_NODE) {
+    const val = node.nodeValue;
+    const parent = node.parentNode;
+    const pos = val.toLowerCase().indexOf(text);
+    if (
+      pos >= 0 &&
+      !parent.classList.contains(className) &&
+      !parent.classList.contains("nohighlight")
+    ) {
+      let span;
+
+      const closestNode = parent.closest("body, svg, foreignObject");
+      const isInSVG = closestNode && closestNode.matches("svg");
+      if (isInSVG) {
+        span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+      } else {
+        span = document.createElement("span");
+        span.classList.add(className);
+      }
+
+      span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+      parent.insertBefore(
+        span,
+        parent.insertBefore(
+          document.createTextNode(val.substr(pos + text.length)),
+          node.nextSibling
+        )
+      );
+      node.nodeValue = val.substr(0, pos);
+
+      if (isInSVG) {
+        const rect = document.createElementNS(
+          "http://www.w3.org/2000/svg",
+          "rect"
+        );
+        const bbox = parent.getBBox();
+        rect.x.baseVal.value = bbox.x;
+        rect.y.baseVal.value = bbox.y;
+        rect.width.baseVal.value = bbox.width;
+        rect.height.baseVal.value = bbox.height;
+        rect.setAttribute("class", className);
+        addItems.push({ parent: parent, target: rect });
+      }
+    }
+  } else if (node.matches && !node.matches("button, select, textarea")) {
+    node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
+  }
+};
+const _highlightText = (thisNode, text, className) => {
+  let addItems = [];
+  _highlight(thisNode, addItems, text, className);
+  addItems.forEach((obj) =>
+    obj.parent.insertAdjacentElement("beforebegin", obj.target)
+  );
+};
+
+/**
+ * Small JavaScript module for the documentation.
+ */
+const SphinxHighlight = {
+
+  /**
+   * highlight the search words provided in localstorage in the text
+   */
+  highlightSearchWords: () => {
+    if (!SPHINX_HIGHLIGHT_ENABLED) return;  // bail if no highlight
+
+    // get and clear terms from localstorage
+    const url = new URL(window.location);
+    const highlight =
+        localStorage.getItem("sphinx_highlight_terms")
+        || url.searchParams.get("highlight")
+        || "";
+    localStorage.removeItem("sphinx_highlight_terms")
+    url.searchParams.delete("highlight");
+    window.history.replaceState({}, "", url);
+
+    // get individual terms from highlight string
+    const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
+    if (terms.length === 0) return; // nothing to do
+
+    // There should never be more than one element matching "div.body"
+    const divBody = document.querySelectorAll("div.body");
+    const body = divBody.length ? divBody[0] : document.querySelector("body");
+    window.setTimeout(() => {
+      terms.forEach((term) => _highlightText(body, term, "highlighted"));
+    }, 10);
+
+    const searchBox = document.getElementById("searchbox");
+    if (searchBox === null) return;
+    searchBox.appendChild(
+      document
+        .createRange()
+        .createContextualFragment(
+          '<p class="highlight-link">' +
+            '<a href="javascript:SphinxHighlight.hideSearchWords()">' +
+            _("Hide Search Matches") +
+            "</a></p>"
+        )
+    );
+  },
+
+  /**
+   * helper function to hide the search marks again
+   */
+  hideSearchWords: () => {
+    document
+      .querySelectorAll("#searchbox .highlight-link")
+      .forEach((el) => el.remove());
+    document
+      .querySelectorAll("span.highlighted")
+      .forEach((el) => el.classList.remove("highlighted"));
+    localStorage.removeItem("sphinx_highlight_terms")
+  },
+
+  initEscapeListener: () => {
+    // only install a listener if it is really needed
+    if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return;
+
+    document.addEventListener("keydown", (event) => {
+      // bail for input elements
+      if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
+      // bail with special keys
+      if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return;
+      if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) {
+        SphinxHighlight.hideSearchWords();
+        event.preventDefault();
+      }
+    });
+  },
+};
+
+_ready(SphinxHighlight.highlightSearchWords);
+_ready(SphinxHighlight.initEscapeListener);