zig/lib/docs/index.html
Loris Cro aa765c1d70 autodoc: add support for defining guide sections
For example:

//!zig-autodoc-section: Advanced Topics
2023-04-15 18:26:53 +02:00

858 lines
24 KiB
HTML

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Documentation - Zig</title>
<link rel="icon" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAgklEQVR4AWMYWuD7EllJIM4G4g4g5oIJ/odhOJ8wToOxSTXgNxDHoeiBMfA4+wGShjyYOCkG/IGqWQziEzYAoUAeiF9D5U+DxEg14DRU7jWIT5IBIOdCxf+A+CQZAAoopEB7QJwBCBwHiip8UYmRdrAlDpIMgApwQZNnNii5Dq0MBgCxxycBnwEd+wAAAABJRU5ErkJggg==">
<style>
:root {
font-size: 1em;
--ui: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
--mono: "Source Code Pro", monospace;
--tx-color: #141414;
--bg-color: #ffffff;
--link-color: #2A6286;
--sidebar-sh-color: rgba(0, 0, 0, 0.09);
--sidebar-pkg-bg-color: #f1f1f1;
--sidebar-pkglnk-tx-color: #141414;
--sidebar-pkglnk-tx-color-hover: #fff;
--sidebar-pkglnk-tx-color-active: #000;
--sidebar-pkglnk-bg-color: transparent;
--sidebar-pkglnk-bg-color-hover: #555;
--sidebar-pkglnk-bg-color-active: #FFBB4D;
--search-bg-color: #f3f3f3;
--search-bg-color-focus: #ffffff;
--search-sh-color: rgba(0, 0, 0, 0.18);
--help-sh-color: rgba(0, 0, 0, 0.75);
--help-bg-color: #aaa;
}
html, body { margin: 0; padding: 0; height: 100%; }
a {
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
.hidden {
display: none;
}
/* layout */
.canvas {
width: 100vw;
height: 100vh;
overflow: hidden;
margin: 0;
padding: 0;
font-family: var(--ui);
color: var(--tx-color);
background-color: var(--bg-color);
}
.flex-main {
display: flex;
width: 100%;
height: 100%;
justify-content: center;
z-index: 100;
}
.flex-filler {
flex-grow: 1;
flex-shrink: 1;
}
.flex-left {
width: 12rem;
max-width: 15vw;
min-width: 9.5rem;
overflow: auto;
-webkit-overflow-scrolling: touch;
overflow-wrap: break-word;
flex-shrink: 0;
flex-grow: 0;
z-index: 300;
}
.flex-right {
display: flex;
overflow: auto;
-webkit-overflow-scrolling: touch;
flex-grow: 1;
flex-shrink: 1;
z-index: 200;
}
.flex-right > .wrap {
width: 60rem;
max-width: 85vw;
flex-shrink: 1;
}
.help-modal {
z-index: 400;
}
/* sidebar */
.sidebar {
font-size: 1rem;
background-color: var(--bg-color);
box-shadow: 0 0 1rem var(--sidebar-sh-color);
}
.sidebar .logo {
padding: 1rem 0.35rem 0.35rem 0.35rem;
}
.sidebar .logo > svg {
display: block;
overflow: visible;
}
.sidebar ul.guides-api-switch {
display: flex;
flex-direction: row;
justify-content: center;
text-align: center;
list-style-type: none;
margin: 0;
padding: 0;
}
.sidebar .guides-api-switch a {
display: block;
padding: 0.5rem 1rem;
color: var(--sidebar-pkglnk-tx-color);
background-color: var(--sidebar-pkglnk-bg-color);
border: 1px solid var(--tx-color);
}
#ApiSwitch {
border-radius: 10px 0 0 10px;
}
#guideSwitch {
border-radius: 0 10px 10px 0;
}
#ApiSwitch:hover, #guideSwitch:hover {
text-decoration: none;
}
#ApiSwitch:hover:not(.active), #guideSwitch:hover:not(.active) {
color: var(--sidebar-pkglnk-tx-color-hover);
background-color: var(--sidebar-pkglnk-bg-color-hover);
}
.sidebar .guides-api-switch .active {
color: var(--sidebar-pkglnk-tx-color-active);
background-color: var(--sidebar-pkglnk-bg-color-active);
}
.sidebar h2 {
margin: 0.5rem;
padding: 0;
font-size: 1.2rem;
}
.sidebar h2 > span {
border-bottom: 0.125rem dotted var(--tx-color);
}
.sidebar .packages {
list-style-type: none;
margin: 0;
padding: 0;
background-color: var(--sidebar-pkg-bg-color);
}
.sidebar .packages > li > a {
display: block;
padding: 0.5rem 1rem;
color: var(--sidebar-pkglnk-tx-color);
background-color: var(--sidebar-pkglnk-bg-color);
text-decoration: none;
}
.sidebar .packages > li > a:hover {
color: var(--sidebar-pkglnk-tx-color-hover);
background-color: var(--sidebar-pkglnk-bg-color-hover);
}
.sidebar .packages > li > a.active {
color: var(--sidebar-pkglnk-tx-color-active);
background-color: var(--sidebar-pkglnk-bg-color-active);
}
.sidebar p.str {
margin: 0.5rem;
font-family: var(--mono);
}
#guides {
padding: 1rem 0.7rem 2.4rem 1.4rem;
box-sizing: border-box;
font-size: 1rem;
background-color: var(--bg-color);
overflow-wrap: break-word;
}
/* docs section */
.docs {
padding: 1rem 0.7rem 2.4rem 1.4rem;
font-size: 1rem;
background-color: var(--bg-color);
overflow-wrap: break-word;
}
.docs .search {
width: 100%;
margin-bottom: 0.8rem;
padding: 0.5rem;
font-family: var(--ui);
font-size: 1rem;
color: var(--tx-color);
background-color: var(--search-bg-color);
border-top: 0;
border-left: 0;
border-right: 0;
border-bottom-width: 0.125rem;
border-bottom-style: solid;
border-bottom-color: var(--tx-color);
outline: none;
transition: border-bottom-color 0.35s, background 0.35s, box-shadow 0.35s;
border-radius: 0;
-webkit-appearance: none;
}
.docs .search:focus {
background-color: var(--search-bg-color-focus);
border-bottom-color: #ffbb4d;
box-shadow: 0 0.3em 1em 0.125em var(--search-sh-color);
}
#searchPlaceholder {
position: absolute;
pointer-events: none;
top: 5px;
left: 5px;
}
.docs a {
color: var(--link-color);
}
.docs p {
margin: 0.8rem 0;
}
.docs pre {
font-family: var(--mono);
font-size: 1em;
background-color: #F5F5F5;
padding: 1em;
overflow-x: auto;
}
.docs code {
font-family: var(--mono);
font-size: 1em;
}
.docs h1 {
font-size: 1.4em;
margin: 0.8em 0;
padding: 0;
border-bottom: 0.0625rem dashed;
}
.docs h2 {
font-size: 1.3em;
margin: 0.5em 0;
padding: 0;
border-bottom: 0.0625rem solid;
}
#listNav {
list-style-type: none;
margin: 0;
padding: 0;
overflow: hidden;
background-color: #f1f1f1;
}
#listNav li {
float:left;
}
#listNav li a {
display: block;
color: #000;
text-align: center;
padding: .5em .8em;
text-decoration: none;
}
#listNav li a:hover {
background-color: #555;
color: #fff;
}
#listNav li a.active {
background-color: #FFBB4D;
color: #000;
}
#listSearchResults li.selected {
background-color: #93e196;
}
#tableFnErrors dt {
font-weight: bold;
}
.expand[open] .sum-less {
display: none;
}
.expand[open] .sum-more {
display: block;
}
.expand .sum-more {
display: none;
}
.expand {
position: relative;
}
.expand .button:before {
content: "[+] ";
font-family: var(--mono);
color: var(--link-color);
position: sticky;
float: left;
top: 0.5em;
right: -16px;
z-index: 1;
margin-left: -2em;
pointer-events: all;
cursor: pointer;
}
.expand[open] .button:before {
content: "[-] ";
}
.examples {
list-style-type: none;
margin: 0;
padding: 0;
}
.examples li {
padding: 0.5em 0;
white-space: nowrap;
overflow-x: auto;
}
.docs td {
margin: 0;
padding: 0.5em;
max-width: 27em;
text-overflow: ellipsis;
overflow-x: hidden;
}
.fieldHasDocs {
margin-bottom: 0;
}
.fieldDocs {
border: 1px solid #F5F5F5;
border-top: 0px;
padding: 1px 1em;
}
/* help modal */
.help-modal {
display: flex;
width: 100%;
height: 100%;
position: fixed;
top: 0;
left: 0;
justify-content: center;
align-items: center;
background-color: rgba(0, 0, 0, 0.15);
backdrop-filter: blur(0.3em);
}
.help-modal > .modal {
max-width: 97vw;
max-height: 97vh;
overflow: auto;
font-size: 1rem;
color: #fff;
background-color: var(--help-bg-color);
border: 0.125rem solid #000;
box-shadow: 0 0.5rem 2.5rem 0.3rem var(--help-sh-color);
}
.help-modal h1 {
margin: 0.75em 2.5em 1em 2.5em;
font-size: 1.5em;
text-align: center;
}
.help-modal dt, .help-modal dd {
display: inline;
margin: 0 0.2em;
}
.help-modal dl {
margin-left: 0.5em;
margin-right: 0.5em;
}
kbd {
display: inline-block;
padding: 0.3em 0.2em;
font-family: var(--mono);
font-size: 1em;
line-height: 0.8em;
vertical-align: middle;
color: #000;
background-color: #fafbfc;
border-color: #d1d5da;
border-bottom-color: #c6cbd1;
border: solid 0.0625em;
border-radius: 0.1875em;
box-shadow: inset 0 -0.2em 0 #c6cbd1;
cursor: default;
}
#listFns > div {
padding-bottom: 10px;
}
#listFns dt {
font-family: var(--mono);
display: flex;
flex-direction: colunm;
justify-content: space-between;
}
#listFns dt .fnSignature {
overflow-x: hidden;
white-space: nowrap;
text-overflow: ellipsis;
}
.argBreaker {
display: none;
}
/* tokens */
.tok-kw {
color: #333;
font-weight: bold;
}
.tok-str {
color: #d14;
}
.tok-builtin {
color: #0086b3;
}
.tok-comment {
color: #777;
font-style: italic;
}
.tok-fn {
color: #900;
font-weight: bold;
}
.tok-null {
color: #008080;
}
.tok-number {
color: #008080;
}
.tok-type {
color: #458;
font-weight: bold;
}
/* dark mode */
@media (prefers-color-scheme: dark) {
:root {
--tx-color: #bbb;
--bg-color: #111;
--link-color: #88f;
--sidebar-sh-color: rgba(128, 128, 128, 0.09);
--sidebar-pkg-bg-color: #333;
--sidebar-pkglnk-tx-color: #fff;
--sidebar-pkglnk-tx-color-hover: #fff;
--sidebar-pkglnk-tx-color-active: #000;
--sidebar-pkglnk-bg-color: transparent;
--sidebar-pkglnk-bg-color-hover: #555;
--sidebar-pkglnk-bg-color-active: #FFBB4D;
--search-bg-color: #3c3c3c;
--search-bg-color-focus: #000;
--search-sh-color: rgba(255, 255, 255, 0.28);
--help-sh-color: rgba(142, 142, 142, 0.5);
--help-bg-color: #333;
}
.docs pre {
background-color:#2A2A2A;
}
.fieldDocs {
border-color:#2A2A2A;
}
#listNav {
background-color: #333;
}
#listNav li a {
color: #fff;
}
#listNav li a:hover {
background-color: #555;
color: #fff;
}
#listNav li a.active {
background-color: #FFBB4D;
color: #000;
}
#listSearchResults li.selected {
background-color: #000;
}
#listSearchResults li.selected a {
color: #fff;
}
.tok-kw {
color: #eee;
}
.tok-str {
color: #2e5;
}
.tok-builtin {
color: #ff894c;
}
.tok-comment {
color: #aa7;
}
.tok-fn {
color: #e33;
}
.tok-null {
color: #ff8080;
}
.tok-number {
color: #ff8080;
}
.tok-type {
color: #68f;
}
}
@media only screen and (max-width: 750px) {
.canvas {
overflow: auto;
}
.flex-main {
flex-direction: column;
display: block;
}
.sidebar {
min-width: calc(100vw - 2.8rem);
padding-left: 1.4rem;
padding-right: 1.4rem;
}
.logo {
max-width: 6.5rem;
}
.flex-main > .flex-filler {
display: none;
}
.flex-main > .flex-right > .flex-filler {
display: none;
}
.flex-main > .flex-right > .wrap {
max-width: 100vw;
}
.flex-main > .flex-right > .wrap > .docs {
padding-right: 1.4rem;
background: transparent;
}
.packages {
display: flex;
flex-wrap: wrap;
}
.table-container table {
display: flex;
flex-direction: column;
}
.table-container tr {
display: flex;
flex-direction: column;
}
.examples {
overflow-x: scroll;
-webkit-overflow-scrolling: touch;
max-width: 100vw;
margin-left: -1.4rem;
margin-right: -1.4rem;
}
.examples li {
width: max-content;
padding-left: 1.4rem;
padding-right: 1.4rem;
}
.mobile-scroll-container {
overflow-x: scroll;
-webkit-overflow-scrolling: touch;
margin-left: -1.4rem;
margin-right: -1.4rem;
max-width: 100vw;
}
.mobile-scroll-container > .scroll-item {
margin-left: 1.4rem;
margin-right: 1.4rem;
box-sizing: border-box;
width: max-content;
display: inline-block;
min-width: calc(100% - 2.8rem);
}
}
.banner {
background-color: orange;
text-align: center;
color: black;
padding: 5px 5px;
}
.banner a {
color: black;
text-decoration: underline;
}
</style>
</head>
<body class="canvas">
<div class="banner">
This is a beta autodoc build; expect bugs and missing information.
<a href="https://github.com/ziglang/zig/wiki/How-to-contribute-to-Autodoc">Report an Issue</a>,
<a href="https://github.com/ziglang/zig/wiki/How-to-contribute-to-Autodoc">Contribute</a>,
<a href="https://github.com/ziglang/zig/wiki/How-to-read-the-standard-library-source-code">Learn more about stdlib source code</a>.
</div>
<div class="flex-main">
<div class="flex-filler"></div>
<div class="flex-left sidebar">
<nav>
<div class="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 140">
<g fill="#F7A41D">
<g>
<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="31,95 12,117 4,106"/>
</g>
<g>
<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="116,95 97,117 90,104"/>
<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"/>
</g>
<g>
<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="125,95 130,110 106,117"/>
</g>
</g>
<style>
#text { fill: #121212 }
@media (prefers-color-scheme: dark) { #text { fill: #f2f2f2 } }
</style>
<g id="text">
<g>
<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="261,99 261,117 176,117 176,103 206,99" shape-rendering="crispEdges"/>
</g>
<rect x="272" y="22" shape-rendering="crispEdges" width="22" height="95"/>
<g>
<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"/>
<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>
</svg>
</div>
<div id="sectGudeApiSwitch">
<ul class="guides-api-switch">
<li><a id="ApiSwitch" class="active" href="#A;">API</a></li>
<li><a id="guideSwitch" class="" href="#G;">Guides</a></li>
</ul>
</div>
<div id="guidesMenu" class="hidden">
<div id="guidesList"></div>
</div>
<div id="apiMenu" class="hidden">
<div id="sectMainPkg" class="hidden">
<h2><span>Main Package</span></h2>
<ul class="packages">
<li><a id="mainPkg" class="" href=""></a></li>
</ul>
</div>
<div id="sectPkgs" class="hidden">
<h2><span>Dependencies</span></h2>
<ul id="listPkgs" class="packages"></ul>
</div>
<div id="sectInfo" class="hidden">
<h2><span>Zig Version</span></h2>
<p class="str" id="tdZigVer"></p>
</div>
<div>
<input id="privDeclsBox" type="checkbox"/>
<label for="privDeclsBox">Internal Doc Mode</label>
</div>
</div>
</nav>
</div>
<div class="flex-right">
<div id="guides" class="wrap hidden">
</div>
<div id="docs" class="wrap hidden">
<section class="docs">
<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>
<div id="sectNav" class="hidden"><ul id="listNav"></ul></div>
<div id="fnProto" class="hidden">
<div class="mobile-scroll-container"><pre id="fnProtoCode" class="scroll-item"></pre></div>
<div id="fnSourceLink" style="display:flex;flex-direction:row;justify-content:flex-end;"></div>
</div>
<h1 id="hdrName" class="hidden"></h1>
<div id="fnNoExamples" class="hidden">
<p>This function is not tested or referenced.</p>
</div>
<div id="declNoRef" class="hidden">
<p>
This declaration is not tested or referenced, and it has therefore not been included in
semantic analysis, which means the only documentation available is whatever is in the
doc comments.
</p>
</div>
<div id="tldDocs" class="hidden"></div>
<div id="sectParams" class="hidden">
<h2>Parameters</h2>
<div id="listParams"></div>
</div>
<div id="sectFnErrors" class="hidden">
<h2>Errors</h2>
<div id="fnErrorsAnyError">
<p><span class="tok-type">anyerror</span> means the error set is known only at runtime.</p>
</div>
<div id="tableFnErrors"><dl id="listFnErrors"></dl></div>
</div>
<div id="sectSearchResults" class="hidden">
<h2>Search Results</h2>
<ul id="listSearchResults"></ul>
<p id="sectSearchAllResultsLink" class="hidden"><a href="">show all results</a></p>
</div>
<div id="sectSearchNoResults" class="hidden">
<h2>No Results Found</h2>
<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>
<div id="listFields"></div>
</div>
<div id="sectTypes" class="hidden">
<h2>Types</h2>
<ul id="listTypes"></ul>
</div>
<div id="sectNamespaces" class="hidden">
<h2>Namespaces</h2>
<ul id="listNamespaces"></ul>
</div>
<div id="sectGlobalVars" class="hidden">
<h2>Global Variables</h2>
<div class="table-container">
<table>
<tbody id="listGlobalVars"></tbody>
</table>
</div>
</div>
<div id="sectFns" class="hidden">
<h2>Functions</h2>
<div class="table-container">
<dl id="listFns"></dl>
</div>
</div>
<div id="sectValues" class="hidden">
<h2>Values</h2>
<div class="table-container">
<table>
<tbody id="listValues"></tbody>
</table>
</div>
</div>
<div id="sectErrSets" class="hidden">
<h2>Error Sets</h2>
<ul id="listErrSets"></ul>
</div>
<div id="fnExamples" class="hidden">
<h2>Examples</h2>
<ul id="listFnExamples" class="examples"></ul>
</div>
<div id="sectDocTests" class="hidden">
<h2>DocTests</h2>
<pre id="docTestsCode"></pre>
</div>
<div id="sectTests" class="hidden">
<h2>Tests</h2>
<div class="table-container">
<table>
<tbody id="listTests"></tbody>
</table>
</div>
</div>
</section>
</div>
<div class="flex-filler"></div>
</div>
</div>
<div id="helpModal" class="hidden">
<div class="help-modal">
<div class="modal">
<h1>Keyboard Shortcuts</h1>
<dl><dt><kbd>?</kbd></dt><dd>Show this help modal</dd></dl>
<dl><dt><kbd>s</kbd></dt><dd>Focus the search field</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>
<script src="data.js"></script>
<script src="main.js"></script>
</body>
</html>