mirror/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2025-12-21 05:33:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #12347 from r00ster91/nicedocs

Browse Source 
autodoc: various improvements
This commit is contained in:
Loris Cro 2022-08-08 18:31:01 +02:00 committed by GitHub
commit 1db99b08e2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 138 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
lib/docs/index.html
View File

@ -25,9 +25,10 @@
--search-bg-color-focus: #ffffff; --search-bg-color-focus: #ffffff;
--search-sh-color: rgba(0, 0, 0, 0.18); --search-sh-color: rgba(0, 0, 0, 0.18);
--help-sh-color: rgba(0, 0, 0, 0.75); --help-sh-color: rgba(0, 0, 0, 0.75);
--help-bg-color: #aaa;
} }
html, body { margin: 0; padding:0; height: 100%; } html, body { margin: 0; padding: 0; height: 100%; }
a { a {
text-decoration: none; text-decoration: none;
@ -190,11 +191,11 @@
box-shadow: 0 0.3em 1em 0.125em var(--search-sh-color); box-shadow: 0 0.3em 1em 0.125em var(--search-sh-color);
} }
.docs .search::placeholder { #searchPlaceholder {
font-size: 1rem; position: absolute;
font-family: var(--ui); pointer-events: none;
color: var(--tx-color); top: 5px;
opacity: 0.5; left: 5px;
} }
.docs a { .docs a {
@ -207,9 +208,9 @@
.docs pre { .docs pre {
font-family: var(--mono); font-family: var(--mono);
font-size:1em; font-size: 1em;
background-color:#F5F5F5; background-color: #F5F5F5;
padding:1em; padding: 1em;
overflow-x: auto; overflow-x: auto;
} }
@ -225,7 +226,7 @@
border-bottom: 0.0625rem dashed; border-bottom: 0.0625rem dashed;
} }
.docs h2 { .docs h2 {
font-size: 1.3em; font-size: 1.3em;
margin: 0.5em 0; margin: 0.5em 0;
padding: 0; padding: 0;
@ -294,7 +295,7 @@
padding: 1px 1em; padding: 1px 1em;
} }
/* help dialog */ /* help modal */
.help-modal { .help-modal {
display: flex; display: flex;
width: 100%; width: 100%;
@ -308,13 +309,13 @@
backdrop-filter: blur(0.3em); backdrop-filter: blur(0.3em);
} }
.help-modal > .dialog { .help-modal > .modal {
max-width: 97vw; max-width: 97vw;
max-height: 97vh; max-height: 97vh;
overflow: auto; overflow: auto;
font-size: 1rem; font-size: 1rem;
color: #fff; color: #fff;
background-color: #333; background-color: var(--help-bg-color);
border: 0.125rem solid #000; border: 0.125rem solid #000;
box-shadow: 0 0.5rem 2.5rem 0.3rem var(--help-sh-color); box-shadow: 0 0.5rem 2.5rem 0.3rem var(--help-sh-color);
} }
@ -335,7 +336,7 @@
margin-right: 0.5em; margin-right: 0.5em;
} }
.help-modal kbd { kbd {
display: inline-block; display: inline-block;
padding: 0.3em 0.2em; padding: 0.3em 0.2em;
font-size: 1.2em; font-size: 1.2em;
@ -348,16 +349,16 @@
border-bottom-color: #c6cbd1; border-bottom-color: #c6cbd1;
border: solid 0.0625em; border: solid 0.0625em;
border-radius: 0.1875em; border-radius: 0.1875em;
box-shadow: inset 0 -0.0625em 0 #c6cbd1; box-shadow: inset 0 -0.2em 0 #c6cbd1;
cursor: default; cursor: default;
} }
#listFns dt { #listFns dt {
font-family: var(--mono); font-family: var(--mono);
} }
.argBreaker { .argBreaker {
display: none; display: none;
} }
/* tokens */ /* tokens */
.tok-kw { .tok-kw {
@ -391,7 +392,6 @@
/* dark mode */ /* dark mode */
@media (prefers-color-scheme: dark) { @media (prefers-color-scheme: dark) {
:root { :root {
--tx-color: #bbb; --tx-color: #bbb;
--bg-color: #111; --bg-color: #111;
@ -408,6 +408,7 @@
--search-bg-color-focus: #000; --search-bg-color-focus: #000;
--search-sh-color: rgba(255, 255, 255, 0.28); --search-sh-color: rgba(255, 255, 255, 0.28);
--help-sh-color: rgba(142, 142, 142, 0.5); --help-sh-color: rgba(142, 142, 142, 0.5);
--help-bg-color: #333;
} }
.docs pre { .docs pre {
@ -457,7 +458,6 @@
.tok-type { .tok-type {
color: #68f; color: #68f;
} }
} }
@media only screen and (max-width: 750px) { @media only screen and (max-width: 750px) {
@ -555,43 +555,43 @@
<div class="logo"> <div class="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 140"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 140">
<g fill="#F7A41D"> <g fill="#F7A41D">
<g> <g>
<polygon points="46,22 28,44 19,30"/> <polygon points="46,22 28,44 19,30"/>
<polygon points="46,22 33,33 28,44 22,44 22,95 31,95 20,100 12,117 0,117 0,22" shape-rendering="crispEdges"/> <polygon points="46,22 33,33 28,44 22,44 22,95 31,95 20,100 12,117 0,117 0,22" shape-rendering="crispEdges"/>
<polygon points="31,95 12,117 4,106"/> <polygon points="31,95 12,117 4,106"/>
</g> </g>
<g> <g>
<polygon points="56,22 62,36 37,44"/> <polygon points="56,22 62,36 37,44"/>
<polygon points="56,22 111,22 111,44 37,44 56,32" shape-rendering="crispEdges"/> <polygon points="56,22 111,22 111,44 37,44 56,32" shape-rendering="crispEdges"/>
<polygon points="116,95 97,117 90,104"/> <polygon points="116,95 97,117 90,104"/>
<polygon points="116,95 100,104 97,117 42,117 42,95" shape-rendering="crispEdges"/> <polygon points="116,95 100,104 97,117 42,117 42,95" shape-rendering="crispEdges"/>
<polygon points="150,0 52,117 3,140 101,22"/> <polygon points="150,0 52,117 3,140 101,22"/>
</g> </g>
<g> <g>
<polygon points="141,22 140,40 122,45"/> <polygon points="141,22 140,40 122,45"/>
<polygon points="153,22 153,117 106,117 120,105 125,95 131,95 131,45 122,45 132,36 141,22" shape-rendering="crispEdges"/> <polygon points="153,22 153,117 106,117 120,105 125,95 131,95 131,45 122,45 132,36 141,22" shape-rendering="crispEdges"/>
<polygon points="125,95 130,110 106,117"/> <polygon points="125,95 130,110 106,117"/>
</g> </g>
</g> </g>
<style> <style>
#text { fill: #121212 } #text { fill: #121212 }
@media (prefers-color-scheme: dark) { #text { fill: #f2f2f2 } } @media (prefers-color-scheme: dark) { #text { fill: #f2f2f2 } }
</style> </style>
<g id="text"> <g id="text">
<g> <g>
<polygon points="260,22 260,37 229,40 177,40 177,22" shape-rendering="crispEdges"/> <polygon points="260,22 260,37 229,40 177,40 177,22" shape-rendering="crispEdges"/>
<polygon points="260,37 207,99 207,103 176,103 229,40 229,37"/> <polygon points="260,37 207,99 207,103 176,103 229,40 229,37"/>
<polygon points="261,99 261,117 176,117 176,103 206,99" shape-rendering="crispEdges"/> <polygon points="261,99 261,117 176,117 176,103 206,99" shape-rendering="crispEdges"/>
</g> </g>
<rect x="272" y="22" shape-rendering="crispEdges" width="22" height="95"/> <rect x="272" y="22" shape-rendering="crispEdges" width="22" height="95"/>
<g> <g>
<polygon points="394,67 394,106 376,106 376,81 360,70 346,67" shape-rendering="crispEdges"/> <polygon points="394,67 394,106 376,106 376,81 360,70 346,67" shape-rendering="crispEdges"/>
<polygon points="360,68 376,81 346,67"/> <polygon points="360,68 376,81 346,67"/>
<path d="M394,106c-10.2,7.3-24,12-37.7,12c-29,0-51.1-20.8-51.1-48.3c0-27.3,22.5-48.1,52-48.1 c14.3,0,29.2,5.5,38.9,14l-13,15c-7.1-6.3-16.8-10-25.9-10c-17,0-30.2,12.9-30.2,29.5c0,16.8,13.3,29.6,30.3,29.6 c5.7,0,12.8-2.3,19-5.5L394,106z"/> <path d="M394,106c-10.2,7.3-24,12-37.7,12c-29,0-51.1-20.8-51.1-48.3c0-27.3,22.5-48.1,52-48.1 c14.3,0,29.2,5.5,38.9,14l-13,15c-7.1-6.3-16.8-10-25.9-10c-17,0-30.2,12.9-30.2,29.5c0,16.8,13.3,29.6,30.3,29.6 c5.7,0,12.8-2.3,19-5.5L394,106z"/>
</g> </g>
</g> </g>
</svg> </svg>
</div> </div>
<div id="sectMainPkg" class="hidden"> <div id="sectMainPkg" class="hidden">
<h2><span>Main Package</span></h2> <h2><span>Main Package</span></h2>
<ul class="packages"> <ul class="packages">
@ -606,16 +606,19 @@
<h2><span>Zig Version</span></h2> <h2><span>Zig Version</span></h2>
<p class="str" id="tdZigVer"></p> <p class="str" id="tdZigVer"></p>
</div> </div>
<div> <div>
<input id="privDeclsBox" type="checkbox"/> <input id="privDeclsBox" type="checkbox"/>
<label for="privDeclsBox">Internal Doc Mode</label> <label for="privDeclsBox">Internal Doc Mode</label>
</div> </div>
</nav> </nav>
</div> </div>
<div class="flex-right"> <div class="flex-right">
<div class="wrap"> <div class="wrap">
<section class="docs"> <section class="docs">
<input type="search" class="search" id="search" autocomplete="off" spellcheck="false" placeholder="`s` to search, `?` to see more options"> <div style="position: relative">
<span id="searchPlaceholder"><kbd>S</kbd> to search, <kbd>?</kbd> for more options</span>
<input type="search" class="search" id="search" autocomplete="off" spellcheck="false" disabled>
</div>
<p id="status">Loading...</p> <p id="status">Loading...</p>
<div id="sectNav" class="hidden"><ul id="listNav"></ul></div> <div id="sectNav" class="hidden"><ul id="listNav"></ul></div>
<div id="fnProto" class="hidden"> <div id="fnProto" class="hidden">
@ -703,17 +706,17 @@
</table> </table>
</div> </div>
</div> </div>
</section> </section>
</div> </div>
<div class="flex-filler"></div> <div class="flex-filler"></div>
</div> </div>
</div> </div>
<div id="helpDialog" class="hidden"> <div id="helpModal" class="hidden">
<div class="help-modal"> <div class="help-modal">
<div class="dialog"> <div class="modal">
<h1>Keyboard Shortcuts</h1> <h1>Keyboard Shortcuts</h1>
<dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd></dl> <dl><dt><kbd>?</kbd></dt><dd>Show this help modal</dd></dl>
<dl><dt><kbd>Esc</kbd></dt><dd>Clear focus; close this dialog</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>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 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>Move down in search results</dd></dl>

122
lib/docs/main.js
View File

@ -3,53 +3,54 @@
var zigAnalysis; var zigAnalysis;
(function () { (function () {
let domStatus = document.getElementById("status"); const domStatus = document.getElementById("status");
let domSectNav = document.getElementById("sectNav"); const domSectNav = document.getElementById("sectNav");
let domListNav = document.getElementById("listNav"); const domListNav = document.getElementById("listNav");
let domSectMainPkg = document.getElementById("sectMainPkg"); const domSectMainPkg = document.getElementById("sectMainPkg");
let domSectPkgs = document.getElementById("sectPkgs"); const domSectPkgs = document.getElementById("sectPkgs");
let domListPkgs = document.getElementById("listPkgs"); const domListPkgs = document.getElementById("listPkgs");
let domSectTypes = document.getElementById("sectTypes"); const domSectTypes = document.getElementById("sectTypes");
let domListTypes = document.getElementById("listTypes"); const domListTypes = document.getElementById("listTypes");
let domSectTests = document.getElementById("sectTests"); const domSectTests = document.getElementById("sectTests");
let domListTests = document.getElementById("listTests"); const domListTests = document.getElementById("listTests");
let domSectNamespaces = document.getElementById("sectNamespaces"); const domSectNamespaces = document.getElementById("sectNamespaces");
let domListNamespaces = document.getElementById("listNamespaces"); const domListNamespaces = document.getElementById("listNamespaces");
let domSectErrSets = document.getElementById("sectErrSets"); const domSectErrSets = document.getElementById("sectErrSets");
let domListErrSets = document.getElementById("listErrSets"); const domListErrSets = document.getElementById("listErrSets");
let domSectFns = document.getElementById("sectFns"); const domSectFns = document.getElementById("sectFns");
let domListFns = document.getElementById("listFns"); const domListFns = document.getElementById("listFns");
let domSectFields = document.getElementById("sectFields"); const domSectFields = document.getElementById("sectFields");
let domListFields = document.getElementById("listFields"); const domListFields = document.getElementById("listFields");
let domSectGlobalVars = document.getElementById("sectGlobalVars"); const domSectGlobalVars = document.getElementById("sectGlobalVars");
let domListGlobalVars = document.getElementById("listGlobalVars"); const domListGlobalVars = document.getElementById("listGlobalVars");
let domSectValues = document.getElementById("sectValues"); const domSectValues = document.getElementById("sectValues");
let domListValues = document.getElementById("listValues"); const domListValues = document.getElementById("listValues");
let domFnProto = document.getElementById("fnProto"); const domFnProto = document.getElementById("fnProto");
let domFnProtoCode = document.getElementById("fnProtoCode"); const domFnProtoCode = document.getElementById("fnProtoCode");
let domSectParams = document.getElementById("sectParams"); const domSectParams = document.getElementById("sectParams");
let domListParams = document.getElementById("listParams"); const domListParams = document.getElementById("listParams");
let domTldDocs = document.getElementById("tldDocs"); const domTldDocs = document.getElementById("tldDocs");
let domSectFnErrors = document.getElementById("sectFnErrors"); const domSectFnErrors = document.getElementById("sectFnErrors");
let domListFnErrors = document.getElementById("listFnErrors"); const domListFnErrors = document.getElementById("listFnErrors");
let domTableFnErrors = document.getElementById("tableFnErrors"); const domTableFnErrors = document.getElementById("tableFnErrors");
let domFnErrorsAnyError = document.getElementById("fnErrorsAnyError"); const domFnErrorsAnyError = document.getElementById("fnErrorsAnyError");
let domFnExamples = document.getElementById("fnExamples"); const domFnExamples = document.getElementById("fnExamples");
// let domListFnExamples = (document.getElementById("listFnExamples")); // const domListFnExamples = (document.getElementById("listFnExamples"));
let domFnNoExamples = document.getElementById("fnNoExamples"); const domFnNoExamples = document.getElementById("fnNoExamples");
let domDeclNoRef = document.getElementById("declNoRef"); const domDeclNoRef = document.getElementById("declNoRef");
let domSearch = document.getElementById("search"); const domSearch = document.getElementById("search");
let domSectSearchResults = document.getElementById("sectSearchResults"); const domSectSearchResults = document.getElementById("sectSearchResults");
let domSectSearchAllResultsLink = document.getElementById("sectSearchAllResultsLink"); const domSectSearchAllResultsLink = document.getElementById("sectSearchAllResultsLink");
let domListSearchResults = document.getElementById("listSearchResults"); const domListSearchResults = document.getElementById("listSearchResults");
let domSectSearchNoResults = document.getElementById("sectSearchNoResults"); const domSectSearchNoResults = document.getElementById("sectSearchNoResults");
let domSectInfo = document.getElementById("sectInfo"); const domSectInfo = document.getElementById("sectInfo");
// let domTdTarget = (document.getElementById("tdTarget")); // const domTdTarget = (document.getElementById("tdTarget"));
let domPrivDeclsBox = document.getElementById("privDeclsBox"); const domPrivDeclsBox = document.getElementById("privDeclsBox");
let domTdZigVer = document.getElementById("tdZigVer"); const domTdZigVer = document.getElementById("tdZigVer");
let domHdrName = document.getElementById("hdrName"); const domHdrName = document.getElementById("hdrName");
let domHelpModal = document.getElementById("helpDialog"); const domHelpModal = document.getElementById("helpModal");
const domSearchPlaceholder = document.getElementById("searchPlaceholder");
let searchTimer = null; let searchTimer = null;
let searchTrimResults = true; let searchTrimResults = true;
@ -104,7 +105,15 @@ var zigAnalysis;
// map of decl index to list of comptime fn calls // map of decl index to list of comptime fn calls
// let nodesToCallsMap = indexNodesToCalls(); // let nodesToCallsMap = indexNodesToCalls();
domSearch.disabled = false;
domSearch.addEventListener("keydown", onSearchKeyDown, false); domSearch.addEventListener("keydown", onSearchKeyDown, false);
domSearch.addEventListener("focus", ev => {
domSearchPlaceholder.classList.add("hidden");
});
domSearch.addEventListener("blur", ev => {
if (domSearch.value.length == 0)
domSearchPlaceholder.classList.remove("hidden");
});
domSectSearchAllResultsLink.addEventListener('click', onClickSearchShowAllResults, false); domSectSearchAllResultsLink.addEventListener('click', onClickSearchShowAllResults, false);
function onClickSearchShowAllResults(ev) { function onClickSearchShowAllResults(ev) {
ev.preventDefault(); ev.preventDefault();
@ -142,6 +151,12 @@ var zigAnalysis;
location.hash = "#root"; location.hash = "#root";
} }
// make the modal disappear if you click outside it
domHelpModal.addEventListener("click", ev => {
if (ev.target.className == "help-modal")
domHelpModal.classList.add("hidden");
});
window.addEventListener("hashchange", onHashChange, false); window.addEventListener("hashchange", onHashChange, false);
window.addEventListener("keydown", onWindowKeyDown, false); window.addEventListener("keydown", onWindowKeyDown, false);
onHashChange(); onHashChange();
@ -2628,6 +2643,10 @@ var zigAnalysis;
updateCurNav(); updateCurNav();
if (domSearch.value !== curNavSearch) { if (domSearch.value !== curNavSearch) {
domSearch.value = curNavSearch; domSearch.value = curNavSearch;
if (domSearch.value.length == 0)
domSearchPlaceholder.classList.remove("hidden");
else
domSearchPlaceholder.classList.add("hidden");
} }
render(); render();
if (imFeelingLucky) { if (imFeelingLucky) {
@ -2749,7 +2768,7 @@ var zigAnalysis;
}); });
} }
// Generic fun/ction // Generic function
if (value.kind == typeKinds.Fn && value.generic_ret != null) { if (value.kind == typeKinds.Fn && value.generic_ret != null) {
let resolvedVal = resolveValue({ expr: value.generic_ret }); let resolvedVal = resolveValue({ expr: value.generic_ret });
if ("type" in resolvedVal.expr) { if ("type" in resolvedVal.expr) {
@ -3343,12 +3362,11 @@ var zigAnalysis;
return operatorCompare(a.decl.name, b.decl.name); return operatorCompare(a.decl.name, b.decl.name);
}); });
let searchTrimmed = false;
var searchTrimmed = false const searchTrimResultsMaxItems = 200;
var searchTrimResultsMaxItems = 200
if (searchTrimResults && matchedItems.length > searchTrimResultsMaxItems) { if (searchTrimResults && matchedItems.length > searchTrimResultsMaxItems) {
matchedItems = matchedItems.slice(0, searchTrimResultsMaxItems) matchedItems = matchedItems.slice(0, searchTrimResultsMaxItems);
searchTrimmed = true searchTrimmed = true;
} }
// Build up the list of search results // Build up the list of search results