Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

move autodocs logic from the compiler into the browser and avoid unnecessary javascript files #16490

Closed
andrewrk opened this issue Jul 22, 2023 · 0 comments · Fixed by #19208
Closed
Labels
accepted This proposal is planned. autodoc The web application for interactive documentation and generation of its assets. proposal This issue suggests modifications. If it also has the "accepted" label then it is planned.
Milestone

Comments

@andrewrk
Copy link
Member

With Disable Cache checked, Firefox downloads 13 MiB over the network for the std lib docs. Meanwhile, a tarball of the standard library source files (GZIP=-9 tar cfz std.tar.gz std/) is only 2.1 MiB. This comparison isn't even counting all the .zig files that get converted into .zig.html. The preprocessing steps that the compiler does bloats the data for dubious benefits, when autodoc could be operating on a more compact data set instead.

Furthermore, #3403 is not implemented yet, and it is a hard requirement that I am imposing. Having all the source code available instead of prerendered in separate html files is the simplest and least wasteful way to implement that feature.

I also would like to see these files deleted from zig:

Especially the lexer. There is absolutely no reason to have this in javascript instead of sharing code with the actual lexer that we have written in zig. I don't want to hear any excuses about passing strings over the wasm/js boundary. There are various strategies to do it cleanly, you just need to use your imagination.

In other software projects, "use the right tool for the job" is a fair mantra. In this particular repository, however, we need to demonstrate that Zig is truly a general-purpose programming language. Please don't invest in any more javascript logic that should be zig logic instead. I'm going to lose my shit if somebody suggests adding a package.json to the docs/ folder.

@andrewrk andrewrk added proposal This issue suggests modifications. If it also has the "accepted" label then it is planned. autodoc The web application for interactive documentation and generation of its assets. labels Jul 22, 2023
@andrewrk andrewrk added this to the 0.12.0 milestone Jul 22, 2023
@andrewrk andrewrk modified the milestones: 0.13.0, 0.12.0 Mar 11, 2024
@andrewrk andrewrk added the accepted This proposal is planned. label Mar 11, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
accepted This proposal is planned. autodoc The web application for interactive documentation and generation of its assets. proposal This issue suggests modifications. If it also has the "accepted" label then it is planned.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant