authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2023-09-17 18:21:31+02:00
committergravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2023-09-17 18:23:21+02:00
logc1e94b28a370bdfe40e8e767b82535e248318aa7
tree4c12fdb0e8a054ad69a1c551744f7c2b82c7eabd
parent33f3a4d840b68eeb863a4afa2d8aa2cd0efe92a9

autodoc: split json payload per field

this will make s3 re-enable compression for the stdlib's autodoc and improve loading times (and data usage) for users alongside this commit the deploy script for the official website is also being updated

3 files changed, 73 insertions(+), 61 deletions(-)

lib/docs/index.html+11-1
...@@ -1226,7 +1226,17 @@...@@ -1226,7 +1226,17 @@
1226 </div>1226 </div>
1227 </div>1227 </div>
1228 </div>1228 </div>
1229 <script src="data.js"></script>1229 <script src="data-typeKinds.js"></script>
1230 <script src="data-rootMod.js"></script>
1231 <script src="data-modules.js"></script>
1232 <script src="data-files.js"></script>
1233 <script src="data-calls.js"></script>
1234 <script src="data-types.js"></script>
1235 <script src="data-decls.js"></script>
1236 <script src="data-exprs.js"></script>
1237 <script src="data-astNodes.js"></script>
1238 <script src="data-comptimeExprs.js"></script>
1239 <script src="data-guideSections.js"></script>
1230 <script src="commonmark.js"></script>1240 <script src="commonmark.js"></script>
1231 <script src="ziglexer.js"></script>1241 <script src="ziglexer.js"></script>
1232 <script src="main.js"></script>1242 <script src="main.js"></script>
lib/docs/main.js+28-18
...@@ -1,6 +1,19 @@...@@ -1,6 +1,19 @@
1"use strict";1"use strict";
22
3var zigAnalysis;3var zigAnalysis = {
4 typeKinds,
5 rootMod,
6 modules,
7 astNodes,
8 calls,
9 files,
10 decls,
11 exprs,
12 types,
13 comptimeExprs,
14 guideSections
15};
16
4let skipNextHashChange = null;17let skipNextHashChange = null;
518
6const NAV_MODES = {19const NAV_MODES = {
...@@ -200,11 +213,8 @@ var scrollHistory = {};...@@ -200,11 +213,8 @@ var scrollHistory = {};
200 window.addEventListener("keydown", onWindowKeyDown, false);213 window.addEventListener("keydown", onWindowKeyDown, false);
201 onHashChange();214 onHashChange();
202215
203 let langRefVersion = zigAnalysis.params.zigVersion;216 // TODO: fix this once langref becomes part of autodoc
204 if (!/^\d+\.\d+\.\d+$/.test(langRefVersion)) {217 let langRefVersion = "master";
205 // the version is probably not released yet
206 langRefVersion = "master";
207 }
208 domLangRefLink.href = `https://ziglang.org/documentation/${langRefVersion}/`;218 domLangRefLink.href = `https://ziglang.org/documentation/${langRefVersion}/`;
209219
210 function renderTitle() {220 function renderTitle() {
...@@ -528,8 +538,8 @@ var scrollHistory = {};...@@ -528,8 +538,8 @@ var scrollHistory = {};
528 }538 }
529539
530 let activeGuide = undefined;540 let activeGuide = undefined;
531 outer: for (let i = 0; i < zigAnalysis.guide_sections.length; i += 1) {541 outer: for (let i = 0; i < zigAnalysis.guideSections.length; i += 1) {
532 const section = zigAnalysis.guide_sections[i];542 const section = zigAnalysis.guideSections[i];
533 for (let j = 0; j < section.guides.length; j += 1) {543 for (let j = 0; j < section.guides.length; j += 1) {
534 const guide = section.guides[j];544 const guide = section.guides[j];
535 if (guide.name == curNav.activeGuide) {545 if (guide.name == curNav.activeGuide) {
...@@ -595,7 +605,7 @@ var scrollHistory = {};...@@ -595,7 +605,7 @@ var scrollHistory = {};
595 domGuideTocList.classList.add("hidden");605 domGuideTocList.classList.add("hidden");
596 domGuideTocListEmtpy.classList.remove("hidden");606 domGuideTocListEmtpy.classList.remove("hidden");
597 607
598 if (zigAnalysis.guide_sections.length > 1 || (zigAnalysis.guide_sections[0].guides.length > 0)) {608 if (zigAnalysis.guideSections.length > 1 || (zigAnalysis.guideSections[0].guides.length > 0)) {
599 renderGuidesIndex();609 renderGuidesIndex();
600 } else {610 } else {
601 noGuidesAtAll();611 noGuidesAtAll();
...@@ -609,8 +619,8 @@ var scrollHistory = {};...@@ -609,8 +619,8 @@ var scrollHistory = {};
609 // TODO: ensure unique hashes619 // TODO: ensure unique hashes
610 // TODO: hash also guides and their headings620 // TODO: hash also guides and their headings
611 function computeGuideHashes() {621 function computeGuideHashes() {
612 for (let i = 1; i < zigAnalysis.guide_sections.length; i += 1) {622 for (let i = 1; i < zigAnalysis.guideSections.length; i += 1) {
613 const section = zigAnalysis.guide_sections[i];623 const section = zigAnalysis.guideSections[i];
614 section.hash = "section-" + slugify(section.name || i);624 section.hash = "section-" + slugify(section.name || i);
615 }625 }
616 }626 }
...@@ -619,8 +629,8 @@ var scrollHistory = {};...@@ -619,8 +629,8 @@ var scrollHistory = {};
619 // main content 629 // main content
620 {630 {
621 let html = "";631 let html = "";
622 for (let i = 0; i < zigAnalysis.guide_sections.length; i += 1) {632 for (let i = 0; i < zigAnalysis.guideSections.length; i += 1) {
623 const section = zigAnalysis.guide_sections[i];633 const section = zigAnalysis.guideSections[i];
624 if (i != 0) { // first section is the default section634 if (i != 0) { // first section is the default section
625 html += "<h2 id='"+ section.hash +"'>" + section.name + "</h2>";635 html += "<h2 id='"+ section.hash +"'>" + section.name + "</h2>";
626 }636 }
...@@ -635,10 +645,10 @@ var scrollHistory = {};...@@ -635,10 +645,10 @@ var scrollHistory = {};
635 // sidebar / fast navigation645 // sidebar / fast navigation
636 {646 {
637 domGuidesMenuTitle.textContent = "Sections";647 domGuidesMenuTitle.textContent = "Sections";
638 if (zigAnalysis.guide_sections.length > 1) {648 if (zigAnalysis.guideSections.length > 1) {
639 let html = "";649 let html = "";
640 for (let i = 1; i < zigAnalysis.guide_sections.length; i += 1) {650 for (let i = 1; i < zigAnalysis.guideSections.length; i += 1) {
641 const section = zigAnalysis.guide_sections[i];651 const section = zigAnalysis.guideSections[i];
642 html += "<li><a href='"+ NAV_MODES.GUIDES + ":" + section.hash +"'>" + section.name + "</a></li>";652 html += "<li><a href='"+ NAV_MODES.GUIDES + ":" + section.hash +"'>" + section.name + "</a></li>";
643 }653 }
644 domGuideTocList.innerHTML = "<ul>"+html+"</ul>";654 domGuideTocList.innerHTML = "<ul>"+html+"</ul>";
...@@ -3978,8 +3988,8 @@ Happy writing!...@@ -3978,8 +3988,8 @@ Happy writing!
3978 }3988 }
39793989
3980 function parseGuides() {3990 function parseGuides() {
3981 for (let j = 0; j < zigAnalysis.guide_sections.length; j += 1) {3991 for (let j = 0; j < zigAnalysis.guideSections.length; j += 1) {
3982 const section = zigAnalysis.guide_sections[j];3992 const section = zigAnalysis.guideSections[j];
3983 for (let i = 0; i < section.guides.length; i += 1) {3993 for (let i = 0; i < section.guides.length; i += 1) {
3984 let reader = new commonmark.Parser({ smart: true });3994 let reader = new commonmark.Parser({ smart: true });
3985 const guide = section.guides[i];3995 const guide = section.guides[i];
src/Autodoc.zig+34-42
...@@ -344,7 +344,6 @@ fn generateZirData(self: *Autodoc, output_dir: std.fs.Dir) !void {...@@ -344,7 +344,6 @@ fn generateZirData(self: *Autodoc, output_dir: std.fs.Dir) !void {
344 }344 }
345345
346 var data = DocData{346 var data = DocData{
347 .params = .{},
348 .modules = self.modules,347 .modules = self.modules,
349 .files = self.files,348 .files = self.files,
350 .calls = self.calls.items,349 .calls = self.calls.items,
...@@ -353,28 +352,41 @@ fn generateZirData(self: *Autodoc, output_dir: std.fs.Dir) !void {...@@ -353,28 +352,41 @@ fn generateZirData(self: *Autodoc, output_dir: std.fs.Dir) !void {
353 .exprs = self.exprs.items,352 .exprs = self.exprs.items,
354 .astNodes = self.ast_nodes.items,353 .astNodes = self.ast_nodes.items,
355 .comptimeExprs = self.comptime_exprs.items,354 .comptimeExprs = self.comptime_exprs.items,
356 .guide_sections = self.guide_sections,355 .guideSections = self.guide_sections,
357 };356 };
358357
359 {358 inline for (comptime std.meta.tags(std.meta.FieldEnum(DocData))) |f| {
360 const data_js_f = try output_dir.createFile("data.js", .{});359 const field_name = @tagName(f);
360 const file_name = "data-" ++ field_name ++ ".js";
361 const data_js_f = try output_dir.createFile(file_name, .{});
361 defer data_js_f.close();362 defer data_js_f.close();
362 var buffer = std.io.bufferedWriter(data_js_f.writer());
363363
364 var buffer = std.io.bufferedWriter(data_js_f.writer());
364 const out = buffer.writer();365 const out = buffer.writer();
365 try out.print(366
366 \\ /** @type {{DocData}} */367 try out.print("var {s} =", .{field_name});
367 \\ var zigAnalysis=368
368 , .{});369 var jsw = std.json.writeStream(out, .{
369 try std.json.stringifyArbitraryDepth(370 .whitespace = .minified,
370 self.arena,371 .emit_null_optional_fields = true,
371 data,372 });
372 .{373
373 .whitespace = .minified,374 switch (f) {
374 .emit_null_optional_fields = true,375 .files => try writeFileTableToJson(data.files, data.modules, &jsw),
375 },376 .guideSections => try writeGuidesToJson(data.guideSections, &jsw),
376 out,377 .modules => try jsw.write(data.modules.values()),
377 );378 else => try jsw.write(@field(data, field_name)),
379 }
380
381 // try std.json.stringifyArbitraryDepth(
382 // self.arena,
383 // @field(data, field.name),
384 // .{
385 // .whitespace = .minified,
386 // .emit_null_optional_fields = true,
387 // },
388 // out,
389 // );
378 try out.print(";", .{});390 try out.print(";", .{});
379391
380 // last thing (that can fail) that we do is flush392 // last thing (that can fail) that we do is flush
...@@ -476,18 +488,12 @@ const Scope = struct {...@@ -476,18 +488,12 @@ const Scope = struct {
476488
477/// The output of our analysis process.489/// The output of our analysis process.
478const DocData = struct {490const DocData = struct {
491 // NOTE: editing fields of DocData requires also updating:
492 // - the deployment script for ziglang.org
493 // - imports in index.html
479 typeKinds: []const []const u8 = std.meta.fieldNames(DocTypeKinds),494 typeKinds: []const []const u8 = std.meta.fieldNames(DocTypeKinds),
480 rootMod: u32 = 0,495 rootMod: u32 = 0,
481 params: struct {
482 zigId: []const u8 = "arst",
483 zigVersion: []const u8 = build_options.version,
484 target: []const u8 = "arst",
485 builds: []const struct { target: []const u8 } = &.{
486 .{ .target = "arst" },
487 },
488 },
489 modules: std.AutoArrayHashMapUnmanaged(*Module, DocModule),496 modules: std.AutoArrayHashMapUnmanaged(*Module, DocModule),
490 errors: []struct {} = &.{},
491497
492 // non-hardcoded stuff498 // non-hardcoded stuff
493 astNodes: []AstNode,499 astNodes: []AstNode,
...@@ -498,7 +504,7 @@ const DocData = struct {...@@ -498,7 +504,7 @@ const DocData = struct {
498 exprs: []Expr,504 exprs: []Expr,
499 comptimeExprs: []ComptimeExpr,505 comptimeExprs: []ComptimeExpr,
500506
501 guide_sections: std.ArrayListUnmanaged(Section),507 guideSections: std.ArrayListUnmanaged(Section),
502508
503 const Call = struct {509 const Call = struct {
504 func: Expr,510 func: Expr,
...@@ -506,20 +512,6 @@ const DocData = struct {...@@ -506,20 +512,6 @@ const DocData = struct {
506 ret: Expr,512 ret: Expr,
507 };513 };
508514
509 pub fn jsonStringify(self: DocData, jsw: anytype) !void {
510 try jsw.beginObject();
511 inline for (comptime std.meta.tags(std.meta.FieldEnum(DocData))) |f| {
512 const f_name = @tagName(f);
513 try jsw.objectField(f_name);
514 switch (f) {
515 .files => try writeFileTableToJson(self.files, self.modules, jsw),
516 .guide_sections => try writeGuidesToJson(self.guide_sections, jsw),
517 .modules => try jsw.write(self.modules.values()),
518 else => try jsw.write(@field(self, f_name)),
519 }
520 }
521 try jsw.endObject();
522 }
523 /// All the type "families" as described by `std.builtin.TypeId`515 /// All the type "families" as described by `std.builtin.TypeId`
524 /// plus a couple extra that are unique to our use case.516 /// plus a couple extra that are unique to our use case.
525 ///517 ///