Merge branch 'master' into autodoc-links

Author: kristoff-it

ci/azure/pipelines.yml

@@ -27,7 +27,7 @@ jobs:
     vmImage: 'windows-2019'
   variables:
     TARGET: 'x86_64-windows-gnu'
-    ZIG_LLVM_CLANG_LLD_NAME: 'zig+llvm+lld+clang-${{ variables.TARGET }}-0.10.0-dev.2931+bdf3fa12f'
+    ZIG_LLVM_CLANG_LLD_NAME: 'zig+llvm+lld+clang-${{ variables.TARGET }}-0.10.0-dev.3524+74673b7f6'
     ZIG_LLVM_CLANG_LLD_URL: 'https://ziglang.org/deps/${{ variables.ZIG_LLVM_CLANG_LLD_NAME }}.zip'
   steps:
   - pwsh: |
@@ -41,6 +41,13 @@ jobs:
       Set-Variable -Name ZIGINSTALLDIR -Value "${ZIGBUILDDIR}\dist"
       Set-Variable -Name ZIGPREFIXPATH -Value "$(Get-Location)\$(ZIG_LLVM_CLANG_LLD_NAME)"
 
+      function CheckLastExitCode {
+        if (!$?) {
+          exit 1
+        }
+        return 0
+      }
+
       # Make the `zig version` number consistent.
       # This will affect the `zig build` command below which uses `git describe`.
       git config core.abbrev 9
@@ -69,6 +76,7 @@ jobs:
         -Dstrip `
         -Duse-zig-libcxx `
         -Dtarget=$(TARGET)
+      CheckLastExitCode
 
       cd -
 
@@ -83,19 +91,37 @@ jobs:
   - pwsh: |
       Set-Variable -Name ZIGINSTALLDIR -Value "$(Get-Location)\build\dist"
 
+      function CheckLastExitCode {
+        if (!$?) {
+          exit 1
+        }
+        return 0
+      }
+
       # Sadly, stage2 is omitted from this build to save memory on the CI server. Once self-hosted is
       # built with itself and does not gobble as much memory, we can enable these tests.
       #& "$ZIGINSTALLDIR\bin\zig.exe" test "..\test\behavior.zig" -fno-stage1 -fLLVM -I "..\test" 2>&1
+      #CheckLastExitCode
 
       & "$ZIGINSTALLDIR\bin\zig.exe" build test-toolchain -Dskip-non-native -Dskip-stage2-tests 2>&1
+      CheckLastExitCode
       & "$ZIGINSTALLDIR\bin\zig.exe" build test-std -Dskip-non-native  2>&1
+      CheckLastExitCode
     name: test
     displayName: 'Test'
 
   - pwsh: |
       Set-Variable -Name ZIGINSTALLDIR -Value "$(Get-Location)\build\dist"
 
+      function CheckLastExitCode {
+        if (!$?) {
+          exit 1
+        }
+        return 0
+      }
+
       & "$ZIGINSTALLDIR\bin\zig.exe" build docs
+      CheckLastExitCode
     timeoutInMinutes: 60
     name: doc
     displayName: 'Documentation'

ci/srht/update_download_page

@@ -103,11 +103,19 @@ cd "$HOME"
 
 # Upload new stdlib autodocs 
 mkdir -p docs_to_upload/documentation/master/std/
-cp "$ZIGDIR/docs/std/index.html" docs_to_upload/documentation/master/std/index.html
-cp "$ZIGDIR/docs/std/data.js" docs_to_upload/documentation/master/std/data.js
-cp "$ZIGDIR/docs/std/main.js" docs_to_upload/documentation/master/std/main.js
-cp "$LANGREF" docs_to_upload/documentation/master/index.html
-$S3CMD put -P --no-mime-magic --recursive --add-header="Cache-Control: max-age=0, must-revalidate" "docs_to_upload/" s3://ziglang.org/
+
+gzip -c -9 "$ZIGDIR/docs/std/index.html" >  docs_to_upload/documentation/master/std/index.html
+gzip -c -9 "$ZIGDIR/docs/std/data.js" > docs_to_upload/documentation/master/std/data.js
+gzip -c -9 "$ZIGDIR/docs/std/main.js" > docs_to_upload/documentation/master/std/main.js
+gzip -c -9 "$LANGREF" > docs_to_upload/documentation/master/index.html
+$S3CMD put -P --no-mime-magic --recursive --add-header="Content-Encoding:gzip" --add-header="Cache-Control: max-age=0, must-revalidate" "docs_to_upload/" s3://ziglang.org/
+
+## Copy without compression:
+# cp "$ZIGDIR/docs/std/index.html" docs_to_upload/documentation/master/std/index.html
+# cp "$ZIGDIR/docs/std/data.js" docs_to_upload/documentation/master/std/data.js
+# cp "$ZIGDIR/docs/std/main.js" docs_to_upload/documentation/master/std/main.js
+# cp "$LANGREF" docs_to_upload/documentation/master/index.html
+# $S3CMD put -P --no-mime-magic --recursive --add-header="Cache-Control: max-age=0, must-revalidate" "docs_to_upload/" s3://ziglang.org/
 
 git clone --depth 1 git@github.com:ziglang/www.ziglang.org.git
 cd www.ziglang.org

lib/docs/index.html

@@ -169,8 +169,8 @@
         width: 100%;
         margin-bottom: 0.8rem;
         padding: 0.5rem;
-        font-size: 1rem;
         font-family: var(--ui);
+        font-size: 1rem;
         color: var(--tx-color);
         background-color: var(--search-bg-color);
         border-top: 0;
@@ -339,8 +339,8 @@
       kbd {
         display: inline-block;
         padding: 0.3em 0.2em;
-        font-size: 1.2em;
-        font-size: var(--mono);
+        font-family: var(--mono);
+        font-size: 1em;
         line-height: 0.8em;
         vertical-align: middle;
         color: #000;
@@ -612,7 +612,7 @@ <h2><span>Zig Version</span></h2>
           </div>
         </nav>
       </div>
-      <div class="flex-right">
+      <div id="docs" class="flex-right">
         <div class="wrap">
           <section class="docs">
             <div style="position: relative">
@@ -654,7 +654,13 @@ <h2>Search Results</h2>
             </div>
             <div id="sectSearchNoResults" class="hidden">
               <h2>No Results Found</h2>
-              <p>Press escape to exit search and then '?' to see more options.</p>
+              <p>Here are some things you can try:</p>
+              <ul>
+                <li>Check out the <a id="langRefLink">Language Reference</a> for the language itself.</li>
+                <li>Check out the <a href="https://ziglang.org/learn/">Learn page</a> for other helpful resources for learning Zig.</li>
+                <li>Use your search engine.</li>
+              </ul>
+              <p>Press <kbd>?</kbd> to see keyboard shortcuts and <kbd>Esc</kbd> to return.</p>
             </div>
             <div id="sectFields" class="hidden">
               <h2>Fields</h2>
@@ -716,11 +722,13 @@ <h2>Tests</h2>
         <div class="modal">
           <h1>Keyboard Shortcuts</h1>
           <dl><dt><kbd>?</kbd></dt><dd>Show this help modal</dd></dl>
-          <dl><dt><kbd>Esc</kbd></dt><dd>Clear focus; close this modal</dd></dl>
           <dl><dt><kbd>s</kbd></dt><dd>Focus the search field</dd></dl>
-          <dl><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd></dl>
-          <dl><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd></dl>
-          <dl><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd></dl>
+          <div style="margin-left: 1em">
+            <dl><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd></dl>
+            <dl><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd></dl>
+            <dl><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd></dl>
+          </div>
+          <dl><dt><kbd>Esc</kbd></dt><dd>Clear focus; close this modal</dd></dl>
         </div>
       </div>
     </div>

lib/docs/main.js

@@ -41,7 +41,7 @@ var zigAnalysis;
   const domSearch = document.getElementById("search");
   const domSectSearchResults = document.getElementById("sectSearchResults");
   const domSectSearchAllResultsLink = document.getElementById("sectSearchAllResultsLink");
-
+  const domDocs = document.getElementById("docs");
   const domListSearchResults = document.getElementById("listSearchResults");
   const domSectSearchNoResults = document.getElementById("sectSearchNoResults");
   const domSectInfo = document.getElementById("sectInfo");
@@ -52,6 +52,7 @@ var zigAnalysis;
   const domHelpModal = document.getElementById("helpModal");
   const domSearchPlaceholder = document.getElementById("searchPlaceholder");
   const sourceFileUrlTemplate = "/src-viewer/{{file}}#L{{line}}"
+  const domLangRefLink = document.getElementById("langRefLink");
 
   let lineCounter = 1;
   let searchTimer = null;
@@ -118,10 +119,10 @@ var zigAnalysis;
   });
   domSectSearchAllResultsLink.addEventListener('click', onClickSearchShowAllResults, false);
   function onClickSearchShowAllResults(ev) {
-      ev.preventDefault();
-      ev.stopPropagation();
-      searchTrimResults = false;
-      onHashChange();
+    ev.preventDefault();
+    ev.stopPropagation();
+    searchTrimResults = false;
+    onHashChange();
   }
 
   domPrivDeclsBox.addEventListener(
@@ -163,6 +164,13 @@ var zigAnalysis;
   window.addEventListener("keydown", onWindowKeyDown, false);
   onHashChange();
 
+  let langRefVersion = zigAnalysis.params.zigVersion;
+  if (!/^\d+\.\d+\.\d+$/.test(langRefVersion)) {
+    // the version is probably not released yet
+    langRefVersion = "master";
+  }
+  domLangRefLink.href = `https://ziglang.org/documentation/${langRefVersion}/`;
+
   function renderTitle() {
     let list = curNav.pkgNames.concat(curNav.declNames);
     let suffix = " - Zig";
@@ -3154,6 +3162,23 @@ var zigAnalysis;
     domSearch.blur();
   }
 
+  // hide the modal if it's visible or return to the previous result page and unfocus the search
+  function onEscape(ev) {
+    if (!domHelpModal.classList.contains("hidden")) {
+      domHelpModal.classList.add("hidden");
+      ev.preventDefault();
+      ev.stopPropagation();
+    } else {
+      domSearch.value = "";
+      domSearch.blur();
+      domSearchPlaceholder.classList.remove("hidden");
+      curSearchIndex = -1;
+      ev.preventDefault();
+      ev.stopPropagation();
+      startSearch();
+    }
+  }
+
   function onSearchKeyDown(ev) {
     switch (getKeyString(ev)) {
       case "Enter":
@@ -3170,19 +3195,15 @@ var zigAnalysis;
         ev.stopPropagation();
         return;
       case "Esc":
-        domSearch.value = "";
-        domSearch.blur();
-        curSearchIndex = -1;
-        ev.preventDefault();
-        ev.stopPropagation();
-        startSearch();
-        return;
+        onEscape(ev);
+        return
       case "Up":
         moveSearchCursor(-1);
         ev.preventDefault();
         ev.stopPropagation();
         return;
       case "Down":
+        // TODO: make the page scroll down if the search cursor is out of the screen
         moveSearchCursor(1);
         ev.preventDefault();
         ev.stopPropagation();
@@ -3251,19 +3272,18 @@ var zigAnalysis;
   function onWindowKeyDown(ev) {
     switch (getKeyString(ev)) {
       case "Esc":
-        if (!domHelpModal.classList.contains("hidden")) {
-          domHelpModal.classList.add("hidden");
+        onEscape(ev);
+        break;
+      case "s":
+        if (domHelpModal.classList.contains("hidden")) {
+          domSearch.focus();
+          domSearch.select();
+          domDocs.scrollTo(0, 0);
           ev.preventDefault();
           ev.stopPropagation();
+          startAsyncSearch();
         }
         break;
-      case "s":
-        domSearch.focus();
-        domSearch.select();
-        ev.preventDefault();
-        ev.stopPropagation();
-        startAsyncSearch();
-        break;
       case "?":
         ev.preventDefault();
         ev.stopPropagation();
@@ -3279,6 +3299,7 @@ var zigAnalysis;
     domHelpModal.style.top =
       window.innerHeight / 2 - domHelpModal.clientHeight / 2 + "px";
     domHelpModal.focus();
+    domSearch.blur();
   }
 
   function clearAsyncSearch() {
@@ -3304,7 +3325,7 @@ var zigAnalysis;
     list.sort();
     return list;
   }
-  
+
   function renderSearch() {
     let matchedItems = [];
     let ignoreCase = curNavSearch.toLowerCase() === curNavSearch;
@@ -3393,13 +3414,13 @@ var zigAnalysis;
         const text = lastPkgName + "." + match.path.declNames.join(".");
         const href = navLink(match.path.pkgNames, match.path.declNames);
 
-        matchedItemsHTML += "<li><a href=\""+ href +"\">"+ text + "</a></li>";
+        matchedItemsHTML += "<li><a href=\"" + href + "\">" + text + "</a></li>";
       }
 
       // Replace the search results using our newly constructed HTML string
       domListSearchResults.innerHTML = matchedItemsHTML;
       if (searchTrimmed) {
-          domSectSearchAllResultsLink.classList.remove("hidden");
+        domSectSearchAllResultsLink.classList.remove("hidden");
       }
       renderSearchCursor();