authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2023-04-22 19:12:13+02:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2023-04-22 19:12:13+02:00
log7e9a76048213a21bd3d20cc4acfd2ffe9b4b06b7
tree0a473e618a9982cd9a0209bc053028eef8497cce
parentad634bca9f12a9de641270478a6abf9495b9846f
parentc5fb245f60039565f7a5a4de412da815f037ab15
signaturebadge-question-mark Signed by PGP key 4AEE18F83AFDEB23

Merge pull request #15332 from der-teufel-programming/autodoc-src-files-dirs

Autodoc: html files for sources scoped with respect to packages

2 files changed, 50 insertions(+), 30 deletions(-)

lib/docs/main.js+13-3
......@@ -66,7 +66,7 @@ const NAV_MODES = {
6666 const domHdrName = document.getElementById("hdrName");
6767 const domHelpModal = document.getElementById("helpModal");
6868 const domSearchPlaceholder = document.getElementById("searchPlaceholder");
69 const sourceFileUrlTemplate = "src/{{file}}.html#L{{line}}"
69 const sourceFileUrlTemplate = "src/{{pkg}}/{{file}}.html#L{{line}}"
7070 const domLangRefLink = document.getElementById("langRefLink");
7171
7272 let searchTimer = null;
......@@ -446,7 +446,7 @@ const NAV_MODES = {
446446
447447 if (activeGuide == undefined) {
448448 const root_file_idx = zigAnalysis.packages[zigAnalysis.rootPkg].file;
449 const root_file_name = zigAnalysis.files[root_file_idx];
449 const root_file_name = getFile(root_file_idx).name;
450450 domGuides.innerHTML = markdown(`
451451 # Zig Guides
452452 These autodocs don't contain any guide.
......@@ -2700,8 +2700,10 @@ const NAV_MODES = {
27002700
27012701 function sourceFileLink(decl) {
27022702 const srcNode = getAstNode(decl.src);
2703 const srcFile = getFile(srcNode.file);
27032704 return sourceFileUrlTemplate.
2704 replace("{{file}}", zigAnalysis.files[srcNode.file]).
2705 replace("{{pkg}}", zigAnalysis.packages[srcFile.pkgIndex].name).
2706 replace("{{file}}", srcFile.name).
27052707 replace("{{line}}", srcNode.line + 1);
27062708 }
27072709
......@@ -4150,6 +4152,14 @@ function addDeclToSearchResults(decl, declIndex, pkgNames, item, list, stack) {
41504152 };
41514153 }
41524154
4155 function getFile(idx) {
4156 const file = zigAnalysis.files[idx];
4157 return {
4158 name: file[0],
4159 pkgIndex: file[1],
4160 };
4161 }
4162
41534163 function getType(idx) {
41544164 const ty = zigAnalysis.types[idx];
41554165 switch (ty[0]) {
src/Autodoc.zig+37-27
......@@ -257,7 +257,7 @@ pub fn generateZirData(self: *Autodoc) !void {
257257
258258 var data = DocData{
259259 .params = .{},
260 .packages = self.packages.values(),
260 .packages = self.packages,
261261 .files = self.files,
262262 .calls = self.calls.items,
263263 .types = self.types.items,
......@@ -315,9 +315,26 @@ pub fn generateZirData(self: *Autodoc) !void {
315315 var files_iterator = self.files.iterator();
316316
317317 while (files_iterator.next()) |entry| {
318 const new_html_path = try std.mem.concat(self.arena, u8, &.{ entry.key_ptr.*.sub_file_path, ".html" });
318 const sub_file_path = entry.key_ptr.*.sub_file_path;
319 const file_package = entry.key_ptr.*.pkg;
320 const package_name = (self.packages.get(file_package) orelse continue).name;
319321
320 const html_file = try createFromPath(html_dir, new_html_path);
322 const file_path = std.fs.path.dirname(sub_file_path) orelse "";
323 const file_name = if (file_path.len > 0) sub_file_path[file_path.len + 1 ..] else sub_file_path;
324
325 const html_file_name = try std.mem.concat(self.arena, u8, &.{ file_name, ".html" });
326 defer self.arena.free(html_file_name);
327
328 const dir_name = try std.fs.path.join(self.arena, &.{ package_name, file_path });
329 defer self.arena.free(dir_name);
330
331 var dir = try html_dir.makeOpenPath(dir_name, .{});
332 defer dir.close();
333
334 const html_file = dir.createFile(html_file_name, .{}) catch |err| switch (err) {
335 error.PathAlreadyExists => try dir.openFile(html_file_name, .{}),
336 else => return err,
337 };
321338 defer html_file.close();
322339 var buffer = std.io.bufferedWriter(html_file.writer());
323340
......@@ -335,26 +352,6 @@ pub fn generateZirData(self: *Autodoc) !void {
335352 try docs_dir.copyFile("index.html", output_dir, "index.html", .{});
336353}
337354
338fn createFromPath(base_dir: std.fs.Dir, path: []const u8) !std.fs.File {
339 var path_tokens = std.mem.tokenize(u8, path, std.fs.path.sep_str);
340 var dir = base_dir;
341 while (path_tokens.next()) |toc| {
342 if (path_tokens.peek() != null) {
343 dir.makeDir(toc) catch |e| switch (e) {
344 error.PathAlreadyExists => {},
345 else => |err| return err,
346 };
347 dir = try dir.openDir(toc, .{});
348 } else {
349 return dir.createFile(toc, .{}) catch |e| switch (e) {
350 error.PathAlreadyExists => try dir.openFile(toc, .{}),
351 else => |err| return err,
352 };
353 }
354 }
355 return error.EmptyPath;
356}
357
358355/// Represents a chain of scopes, used to resolve decl references to the
359356/// corresponding entry in `self.decls`. It also keeps track of whether
360357/// a given decl has been analyzed or not.
......@@ -419,7 +416,7 @@ const DocData = struct {
419416 .{ .target = "arst" },
420417 },
421418 },
422 packages: []const DocPackage,
419 packages: std.AutoArrayHashMapUnmanaged(*Package, DocPackage),
423420 errors: []struct {} = &.{},
424421
425422 // non-hardcoded stuff
......@@ -451,8 +448,12 @@ const DocData = struct {
451448 const f_name = @tagName(f);
452449 try jsw.objectField(f_name);
453450 switch (f) {
454 .files => try writeFileTableToJson(self.files, &jsw),
451 .files => try writeFileTableToJson(self.files, self.packages, &jsw),
455452 .guide_sections => try writeGuidesToJson(self.guide_sections, &jsw),
453 .packages => {
454 try std.json.stringify(self.packages.values(), opts, w);
455 jsw.state_index -= 1;
456 },
456457 else => {
457458 try std.json.stringify(@field(self, f_name), opts, w);
458459 jsw.state_index -= 1;
......@@ -952,7 +953,7 @@ fn walkInstruction(
952953 .table = .{},
953954 };
954955
955 // TODO: Add this package as a dependency to the current pakcage
956 // TODO: Add this package as a dependency to the current package
956957 // TODO: this seems something that could be done in bulk
957958 // at the beginning or the end, or something.
958959 const root_src_dir = other_package.root_src_directory;
......@@ -4635,12 +4636,21 @@ fn cteTodo(self: *Autodoc, msg: []const u8) error{OutOfMemory}!DocData.WalkResul
46354636 return DocData.WalkResult{ .expr = .{ .comptimeExpr = cte_slot_index } };
46364637}
46374638
4638fn writeFileTableToJson(map: std.AutoArrayHashMapUnmanaged(*File, usize), jsw: anytype) !void {
4639fn writeFileTableToJson(
4640 map: std.AutoArrayHashMapUnmanaged(*File, usize),
4641 pkgs: std.AutoArrayHashMapUnmanaged(*Package, DocData.DocPackage),
4642 jsw: anytype,
4643) !void {
46394644 try jsw.beginArray();
46404645 var it = map.iterator();
46414646 while (it.next()) |entry| {
4647 try jsw.arrayElem();
4648 try jsw.beginArray();
46424649 try jsw.arrayElem();
46434650 try jsw.emitString(entry.key_ptr.*.sub_file_path);
4651 try jsw.arrayElem();
4652 try jsw.emitNumber(pkgs.getIndex(entry.key_ptr.*.pkg) orelse 0);
4653 try jsw.endArray();
46444654 }
46454655 try jsw.endArray();
46464656}