-
-
Notifications
You must be signed in to change notification settings - Fork 2.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
proof of concept of stage1 doc generation
This commit adds `-fgenerate-docs` CLI option, and it outputs: * doc/index.html * doc/data.js * doc/main.js In this strategy, we have 1 static html page and 1 static javascript file, which loads the semantic analysis dump directly and renders it using dom manipulation. Currently, all it does is list the declarations. But there is a lot more data available to work with. The next step would be making the declarations hyperlinks, and handling page navigation. Another strategy would be to generate a static site with no javascript, based on the semantic analysis dump that zig now provides. I invite the Zig community to take on such a project. However this version which heavily relies on javascript will also be a direction explored. I also welcome contributors to improve the html, css, and javascript of what this commit started, as well as whatever improvements are necessary to the static analysis dumping code to provide more information. See #21.
- Loading branch information
Showing
7 changed files
with
212 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| <!doctype html> | ||
| <html> | ||
| <head> | ||
| <meta charset="utf-8"> | ||
| <title>Documentation - Zig</title> | ||
| <link rel="icon" href="favicon.png"> | ||
| <style type="text/css"> | ||
| .hidden { | ||
| display: none; | ||
| } | ||
|
|
||
| @media (prefers-color-scheme: dark) { | ||
| body{ | ||
| background-color: #111; | ||
| color: #bbb; | ||
| } | ||
| } | ||
| </style> | ||
| </head> | ||
| <body> | ||
| <p id="status">Loading...</p> | ||
| <div id="sectPkgs" class="hidden"> | ||
| <h2>Packages</h2> | ||
| <ul id="listPkgs"> | ||
| </ul> | ||
| </div> | ||
| <div id="sectTypes" class="hidden"> | ||
| <h2>Types</h2> | ||
| <ul id="listTypes"> | ||
| </ul> | ||
| </div> | ||
| <script src="data.js"></script> | ||
| <script src="main.js"></script> | ||
| </body> | ||
| </html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| (function() { | ||
| var domStatus = document.getElementById("status"); | ||
| var domSectPkgs = document.getElementById("sectPkgs"); | ||
| var domListPkgs = document.getElementById("listPkgs"); | ||
| var domSectTypes = document.getElementById("sectTypes"); | ||
| var domListTypes = document.getElementById("listTypes"); | ||
|
|
||
| var curNav = { | ||
| kind: "pkg", | ||
| index: zigAnalysis.rootPkg, | ||
| }; | ||
|
|
||
| var rootIsStd = detectRootIsStd(); | ||
| var typeKindTypeId = findTypeKindType(); | ||
| var typeTypeId = findTypeTypeId(); | ||
| render(); | ||
|
|
||
| function render() { | ||
| domStatus.classList.add("hidden"); | ||
|
|
||
| if (curNav.kind === "pkg") { | ||
| var pkg = zigAnalysis.packages[curNav.index]; | ||
| renderPkgList(pkg); | ||
| var pkgStruct = zigAnalysis.types[pkg.main]; | ||
| renderContainer(pkgStruct); | ||
| } else { | ||
| throw new Error("TODO"); | ||
| } | ||
| } | ||
|
|
||
| function renderPkgList(pkg) { | ||
| var list = []; | ||
| for (var key in pkg.table) { | ||
| if (key === "root" && rootIsStd) continue; | ||
| list.push({ | ||
| name: key, | ||
| pkg: pkg.table[key], | ||
| }); | ||
| } | ||
| list.sort(function(a, b) { | ||
| return operatorCompare(a.name.toLowerCase(), b.name.toLowerCase()); | ||
| }); | ||
|
|
||
| resizeDomList(domListPkgs, list.length, '<li></li>'); | ||
| var domItems = domListPkgs.children; | ||
| for (var i = 0; i < list.length; i += 1) { | ||
| var domItem = domItems[i]; | ||
| domItem.textContent = list[i].name; | ||
| } | ||
|
|
||
| domSectPkgs.classList.remove("hidden"); | ||
| } | ||
|
|
||
| function resizeDomList(listDom, desiredLen, templateHtml) { | ||
| // add the missing dom entries | ||
| var i, ev; | ||
| for (i = listDom.childElementCount; i < desiredLen; i += 1) { | ||
| listDom.insertAdjacentHTML('beforeend', templateHtml); | ||
| } | ||
| // remove extra dom entries | ||
| while (desiredLen < listDom.childElementCount) { | ||
| listDom.removeChild(listDom.lastChild); | ||
| } | ||
| } | ||
|
|
||
| function renderContainer(container) { | ||
| // Find only the types of this package | ||
| var list = []; | ||
| for (var i = 0; i < container.decls.length; i += 1) { | ||
| var decl = zigAnalysis.decls[container.decls[i]]; | ||
| if (decl.type == typeTypeId) { | ||
| list.push(decl); | ||
| } | ||
| } | ||
| list.sort(function(a, b) { | ||
| return operatorCompare(a.name.toLowerCase(), b.name.toLowerCase()); | ||
| }); | ||
|
|
||
| resizeDomList(domListTypes, list.length, '<li></li>'); | ||
| for (var i = 0; i < list.length; i += 1) { | ||
| var domItem = domListTypes.children[i]; | ||
| var decl = list[i]; | ||
| domItem.textContent = decl.name; | ||
| } | ||
|
|
||
| domSectTypes.classList.remove("hidden"); | ||
| } | ||
|
|
||
| function operatorCompare(a, b) { | ||
| if (a === b) { | ||
| return 0; | ||
| } else if (a < b) { | ||
| return -1; | ||
| } else { | ||
| return 1; | ||
| } | ||
| } | ||
|
|
||
| function detectRootIsStd() { | ||
| var rootPkg = zigAnalysis.packages[zigAnalysis.rootPkg]; | ||
| if (rootPkg.table["std"] == null) { | ||
| // no std mapped into the root package | ||
| return false; | ||
| } | ||
| var stdPkg = zigAnalysis.packages[rootPkg.table["std"]]; | ||
| return rootPkg.file === stdPkg.file; | ||
| } | ||
|
|
||
| function findTypeKindType() { | ||
| for (var i = 0; i < zigAnalysis.typeKinds.length; i += 1) { | ||
| if (zigAnalysis.typeKinds[i] === "Type") { | ||
| return i; | ||
| } | ||
| } | ||
| throw new Error("No type kind 'Type' found"); | ||
| } | ||
|
|
||
| function findTypeTypeId() { | ||
| for (var i = 0; i < zigAnalysis.types.length; i += 1) { | ||
| if (zigAnalysis.types[i].kind == typeKindTypeId) { | ||
| return i; | ||
| } | ||
| } | ||
| throw new Error("No type 'type' found"); | ||
| } | ||
| })(); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters