Merge pull request #1579 from p-l-/update-doc

Update doc build

web/static/doc/_static/basic.css

@@ -237,6 +237,10 @@ a.headerlink {
     visibility: hidden;
 }
 
+a:visited {
+    color: #551A8B;
+}
+
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
 h3:hover > a.headerlink,
@@ -670,6 +674,16 @@ dd {
     margin-left: 30px;
 }
 
+.sig dd {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
+.sig dl {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
 dl > dd:last-child,
 dl > dd:last-child > :last-child {
     margin-bottom: 0;
@@ -738,6 +752,14 @@ abbr, acronym {
     cursor: help;
 }
 
+.translated {
+    background-color: rgba(207, 255, 207, 0.2)
+}
+
+.untranslated {
+    background-color: rgba(255, 207, 207, 0.2)
+}
+
 /* -- code displays --------------------------------------------------------- */
 
 pre {

web/static/doc/_static/documentation_options.js

@@ -1,5 +1,4 @@
-var DOCUMENTATION_OPTIONS = {
-    URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
+const DOCUMENTATION_OPTIONS = {
     VERSION: '',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,

web/static/doc/_static/searchtools.js

@@ -57,12 +57,12 @@ const _removeChildren = (element) => {
 const _escapeRegExp = (string) =>
   string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
 
-const _displayItem = (item, searchTerms) => {
+const _displayItem = (item, searchTerms, highlightTerms) => {
   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 contentRoot = document.documentElement.dataset.content_root;
 
   const [docName, title, anchor, descr, score, _filename] = item;
 
@@ -75,20 +75,24 @@ const _displayItem = (item, searchTerms) => {
     if (dirname.match(/\/index\/$/))
       dirname = dirname.substring(0, dirname.length - 6);
     else if (dirname === "index/") dirname = "";
-    requestUrl = docUrlRoot + dirname;
+    requestUrl = contentRoot + dirname;
     linkUrl = requestUrl;
   } else {
     // normal html builders
-    requestUrl = docUrlRoot + docName + docFileSuffix;
+    requestUrl = contentRoot + docName + docFileSuffix;
     linkUrl = docName + docLinkSuffix;
   }
   let linkEl = listItem.appendChild(document.createElement("a"));
   linkEl.href = linkUrl + anchor;
   linkEl.dataset.score = score;
   linkEl.innerHTML = title;
-  if (descr)
+  if (descr) {
     listItem.appendChild(document.createElement("span")).innerHTML =
       " (" + descr + ")";
+    // highlight search terms in the description
+    if (SPHINX_HIGHLIGHT_ENABLED)  // set in sphinx_highlight.js
+      highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
+  }
   else if (showSearchSummary)
     fetch(requestUrl)
       .then((responseData) => responseData.text())
@@ -97,6 +101,9 @@ const _displayItem = (item, searchTerms) => {
           listItem.appendChild(
             Search.makeSearchSummary(data, searchTerms)
           );
+        // highlight search terms in the summary
+        if (SPHINX_HIGHLIGHT_ENABLED)  // set in sphinx_highlight.js
+          highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
       });
   Search.output.appendChild(listItem);
 };
@@ -115,14 +122,15 @@ const _finishSearch = (resultCount) => {
 const _displayNextItem = (
   results,
   resultCount,
-  searchTerms
+  searchTerms,
+  highlightTerms,
 ) => {
   // results left, load the summary and display it
   // this is intended to be dynamic (don't sub resultsCount)
   if (results.length) {
-    _displayItem(results.pop(), searchTerms);
+    _displayItem(results.pop(), searchTerms, highlightTerms);
     setTimeout(
-      () => _displayNextItem(results, resultCount, searchTerms),
+      () => _displayNextItem(results, resultCount, searchTerms, highlightTerms),
       5
     );
   }
@@ -360,7 +368,7 @@ const Search = {
     // console.info("search results:", Search.lastresults);
 
     // print the results
-    _displayNextItem(results, results.length, searchTerms);
+    _displayNextItem(results, results.length, searchTerms, highlightTerms);
   },
 
   /**

web/static/doc/_static/sphinx_highlight.js

@@ -29,14 +29,19 @@ const _highlight = (node, addItems, text, className) => {
       }
 
       span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+      const rest = document.createTextNode(val.substr(pos + text.length));
       parent.insertBefore(
         span,
         parent.insertBefore(
-          document.createTextNode(val.substr(pos + text.length)),
+          rest,
           node.nextSibling
         )
       );
       node.nodeValue = val.substr(0, pos);
+      /* There may be more occurrences of search term in this node. So call this
+       * function recursively on the remaining fragment.
+       */
+      _highlight(rest, addItems, text, className);
 
       if (isInSVG) {
         const rect = document.createElementNS(
@@ -140,5 +145,10 @@ const SphinxHighlight = {
   },
 };
 
-_ready(SphinxHighlight.highlightSearchWords);
-_ready(SphinxHighlight.initEscapeListener);
+_ready(() => {
+  /* Do not call highlightSearchWords() when we are on the search page.
+   * It will highlight words from the *previous* search query.
+   */
+  if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords();
+  SphinxHighlight.initEscapeListener();
+});

web/static/doc/dev/index.html

@@ -12,11 +12,11 @@
     <script src="../_static/js/html5shiv.min.js"></script>
   <![endif]-->
 
-        <script src="../_static/jquery.js"></script>
-        <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
-        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
-        <script src="../_static/doctools.js"></script>
-        <script src="../_static/sphinx_highlight.js"></script>
+        <script src="../_static/jquery.js?v=5d32c60e"></script>
+        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
+        <script src="../_static/documentation_options.js?v=5929fcd5"></script>
+        <script src="../_static/doctools.js?v=888ff710"></script>
+        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/js/theme.js"></script>
     <link rel="index" title="Index" href="../genindex.html" />
     <link rel="search" title="Search" href="../search.html" />
@@ -95,7 +95,7 @@
            <div itemprop="articleBody">
 
   <section id="development">
-<h1>Development<a class="headerlink" href="#development" title="Permalink to this heading"></a></h1>
+<h1>Development<a class="headerlink" href="#development" title="Link to this heading"></a></h1>
 <div class="toctree-wrapper compound">
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="web-api.html">Web API</a></li>

web/static/doc/dev/linting.html

@@ -12,11 +12,11 @@
     <script src="../_static/js/html5shiv.min.js"></script>
   <![endif]-->
 
-        <script src="../_static/jquery.js"></script>
-        <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
-        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
-        <script src="../_static/doctools.js"></script>
-        <script src="../_static/sphinx_highlight.js"></script>
+        <script src="../_static/jquery.js?v=5d32c60e"></script>
+        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
+        <script src="../_static/documentation_options.js?v=5929fcd5"></script>
+        <script src="../_static/doctools.js?v=888ff710"></script>
+        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/js/theme.js"></script>
     <link rel="index" title="Index" href="../genindex.html" />
     <link rel="search" title="Search" href="../search.html" />
@@ -100,7 +100,7 @@
            <div itemprop="articleBody">
 
   <section id="code-linting">
-<h1>Code linting<a class="headerlink" href="#code-linting" title="Permalink to this heading"></a></h1>
+<h1>Code linting<a class="headerlink" href="#code-linting" title="Link to this heading"></a></h1>
 <p>IVRE uses code linters to prevent some easy-to-spot (for a computer)
 mistakes and to enforce a consistent code style (or at least, attempt
 to do so).</p>
@@ -112,7 +112,7 @@ <h1>Code linting<a class="headerlink" href="#code-linting" title="Permalink to t
 be a good PR idea!</p>
 <p>For all the code and the documentation, we also use <a class="reference external" href="https://github.com/codespell-project/codespell">Codespell</a> to prevent typos.</p>
 <section id="running-the-linters">
-<h2>Running the linters<a class="headerlink" href="#running-the-linters" title="Permalink to this heading"></a></h2>
+<h2>Running the linters<a class="headerlink" href="#running-the-linters" title="Link to this heading"></a></h2>
 <p>To install the Python code linters and Codespell you can simply use
 the <code class="docutils literal notranslate"><span class="pre">requirements-linting.txt</span></code> file with Pip, or use any method to
 install the latest versions of the <code class="docutils literal notranslate"><span class="pre">black</span></code>, <code class="docutils literal notranslate"><span class="pre">codespell</span></code>,
@@ -121,7 +121,7 @@ <h2>Running the linters<a class="headerlink" href="#running-the-linters" title="
 expected options and exceptions.</p>
 </section>
 <section id="github-actions">
-<h2>GitHub actions<a class="headerlink" href="#github-actions" title="Permalink to this heading"></a></h2>
+<h2>GitHub actions<a class="headerlink" href="#github-actions" title="Link to this heading"></a></h2>
 <p>Code linting and spell checking is performed in a dedicated <a class="reference external" href="https://github.com/ivre/ivre/actions/workflows/linting.yml">GitHub
 action</a>
 (see <a class="reference internal" href="tests.html#github-actions"><span class="std std-ref">GitHub actions</span></a>), togethter with the Maxmind

web/static/doc/dev/tests.html

@@ -12,11 +12,11 @@
     <script src="../_static/js/html5shiv.min.js"></script>
   <![endif]-->
 
-        <script src="../_static/jquery.js"></script>
-        <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
-        <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
-        <script src="../_static/doctools.js"></script>
-        <script src="../_static/sphinx_highlight.js"></script>
+        <script src="../_static/jquery.js?v=5d32c60e"></script>
+        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
+        <script src="../_static/documentation_options.js?v=5929fcd5"></script>
+        <script src="../_static/doctools.js?v=888ff710"></script>
+        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/js/theme.js"></script>
     <link rel="index" title="Index" href="../genindex.html" />
     <link rel="search" title="Search" href="../search.html" />
@@ -104,16 +104,16 @@
            <div itemprop="articleBody">
 
   <section id="tests">
-<h1>Tests<a class="headerlink" href="#tests" title="Permalink to this heading"></a></h1>
+<h1>Tests<a class="headerlink" href="#tests" title="Link to this heading"></a></h1>
 <p>The <code class="docutils literal notranslate"><span class="pre">tests</span></code> directory is mainly intended for people who want to
 contribute to IVRE and want to make sure their changes do not break
 IVRE.</p>
 <section id="dependencies">
-<h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this heading"></a></h2>
+<h2>Dependencies<a class="headerlink" href="#dependencies" title="Link to this heading"></a></h2>
 <p>To run IVRE tests you will need <a class="reference external" href="http://nedbatchelder.com/code/coverage/">coverage.py</a>.</p>
 </section>
 <section id="test-case">
-<h2>Test case<a class="headerlink" href="#test-case" title="Permalink to this heading"></a></h2>
+<h2>Test case<a class="headerlink" href="#test-case" title="Link to this heading"></a></h2>
 <p>The first thing is to find samples. You need both (recent) Nmap XML scan
 result files (or Nmap JSON files, as generated by
 <code class="docutils literal notranslate"><span class="pre">ivre</span> <span class="pre">scancli</span> <span class="pre">--json</span></code>) and PCAP files (dump while you browse, and
@@ -137,7 +137,7 @@ <h2>Test case<a class="headerlink" href="#test-case" title="Permalink to this he
 </ul>
 </section>
 <section id="first-run">
-<h2>First run<a class="headerlink" href="#first-run" title="Permalink to this heading"></a></h2>
+<h2>First run<a class="headerlink" href="#first-run" title="Link to this heading"></a></h2>
 <p>From the <code class="docutils literal notranslate"><span class="pre">tests</span></code> directory, create the <code class="docutils literal notranslate"><span class="pre">samples</span></code> subdirectory and
 place your samples there (the PCAP files must have the extension
 <code class="docutils literal notranslate"><span class="pre">.pcap</span></code>, the Nmap XML result files must have the extension <code class="docutils literal notranslate"><span class="pre">.xml</span></code>,
@@ -156,7 +156,7 @@ <h2>First run<a class="headerlink" href="#first-run" title="Permalink to this he
 </ul>
 </section>
 <section id="improving-the-test-case">
-<h2>Improving the test case<a class="headerlink" href="#improving-the-test-case" title="Permalink to this heading"></a></h2>
+<h2>Improving the test case<a class="headerlink" href="#improving-the-test-case" title="Link to this heading"></a></h2>
 <p>If you want to make sure to have enough samples, you can:</p>
 <ul class="simple">
 <li><p>Check the <code class="docutils literal notranslate"><span class="pre">samples/results</span></code> file for <code class="docutils literal notranslate"><span class="pre">*_count</span></code> entries with low
@@ -168,7 +168,7 @@ <h2>Improving the test case<a class="headerlink" href="#improving-the-test-case"
 </ul>
 </section>
 <section id="failures">
-<h2>Failures<a class="headerlink" href="#failures" title="Permalink to this heading"></a></h2>
+<h2>Failures<a class="headerlink" href="#failures" title="Link to this heading"></a></h2>
 <p>Tests failure are not always an issue. Apart from a new bug, of course,
 here are some reasons that can explain test failures:</p>
 <ul class="simple">
@@ -180,7 +180,7 @@ <h2>Failures<a class="headerlink" href="#failures" title="Permalink to this head
 </ul>
 </section>
 <section id="github-actions">
-<h2>GitHub actions<a class="headerlink" href="#github-actions" title="Permalink to this heading"></a></h2>
+<h2>GitHub actions<a class="headerlink" href="#github-actions" title="Link to this heading"></a></h2>
 <p>Tests are run with several MongoDB and PostgreSQL versions, as well as
 TinyDB, SQLite and Elasticsearch for each pull requests. The tests run
 with Python 3.7 to 3.11.</p>