-femit-docs: issues around private/public doc viewing

[reader-lamp]

following this:

https://zig.guide/build-system/generating-documentation

it seems you can create docs using one of these:

zig build-lib -femit-docs hello.zig
zig build-obj -femit-docs hello.zig
zig test -femit-docs hello.zig

however build-lib creates extra files:

hello.lib
hello.lib.obj

and build-obj creates extra files:

hello.obj
hello.obj.obj

and test runs the tests, when I just want to create the documentation. moving on, we are left with this:

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---          2025-05-11  4:22 PM          12,786 index.html
-a---          2025-05-11  4:22 PM          34,616 main.js
-a---          2025-05-11  4:22 PM         200,771 main.wasm
-a---          2025-05-11  4:22 PM      14,344,704 sources.tar

the above has several issues. because the JS is making network requests:

zig/lib/docs/main.js

Lines 82 to 83 in c390671

	let wasm_promise = fetch("main.wasm");
	let sources_promise = fetch("sources.tar").then(function(response) {

you cannot just load the HTML into a browser:

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the
remote resource at file:///C:/docs/main.wasm. (Reason: CORS request not http).

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the
remote resource at file:///C:/docs/sources.tar. (Reason: CORS request not http).

you need to run a local file server. moving on, some of these already have a hosted version:

• https://ziglang.org/documentation/master/std/main.wasm
• https://ziglang.org/documentation/master/std/sources.tar

we can edit the JS, but errors are returned:

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the
remote resource at https://ziglang.org/documentation/master/std/sources.tar.
(Reason: CORS header ‘Access-Control-Allow-Origin’ missing).

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the
remote resource at https://ziglang.org/documentation/master/std/main.wasm.
(Reason: CORS header ‘Access-Control-Allow-Origin’ missing).

so we must host the source code for the entire Zig standard library. another issue is if we want to use GitHub for hosting the docs, we would have to put main.wasm and sources.tar into version control, which is bad because they are both large binary files. I think the above points are creating a situation where not many people are hosting Zig docs. to give an example I was looking for a Zig ProtoBuf module, and came across these:

1. https://github.com/Arwalk/zig-protobuf
2. https://github.com/allyourcodebase/protobuf-c
3. https://github.com/fengb/zig-protobuf
4. https://github.com/kubkon/protozig
5. https://github.com/mlugg/zigpb
6. https://github.com/rjsberry/pb.zig
7. https://github.com/shailpatels/zig-protobuf
8. https://github.com/travisstaloch/protobuf-zig
9. https://github.com/zigtools/protobruh

none of which are hosting their own docs, on GitHub or otherwise.

[reader-lamp]

to add to the above, other languages can create docs without compiling or running tests. for example this is some invalid Go code:

package hello

func World() int {
   return ""
}

result:

cannot use "" (untyped string constant) as int value in return statement

but it will still produce docs:

> go doc
package hello // import "hello"

func World() int

[xdBronch]

what exactly is the problem statement of this issue?
redundant files being emitted is a bug unrelated to docs and they can simply be deleted and you can use zig test --test-no-exec to compile but not run tests.
needing to run a web server to view the docs is a limitation browsers place on wasm and not something that zig can control. i dont really see the problem with that if your goal is to host the docs on a server anyway.
all but 2 of the protobuf links are outdated and 1 of them is just a C library packaged with zig, it wouldnt make any sense for them to host docs.

[reader-lamp]

what exactly is the problem statement of this issue?

the viewing of Zig docs both privately and publicly is more difficult than it needs to be. privately the docs could be generated as static HTML files or similar, instead of having JS make network requests - if that was done you could avoid a local web server. if the WASM approach must remain, we could at least allow the remote WASM and TAR files to be used by fixing the CORS errors, which would result in a situation where you could avoid having to generate those files locally, and avoid having to host them on GitHub or anywhere else

redundant files being emitted is a bug unrelated to docs and they can simply be deleted and you can use zig test --test-no-exec to compile but not run tests.

this is helpful, but ideally we could generate docs without compiling, as in the example above. also I just realized that neither test example seem to work with multiple files

#10018

needing to run a web server to view the docs is a limitation browsers place on wasm and not something that zig can control.

incorrect, Zig could produce docs that do not make a network request, then no web server is needed

i dont really see the problem with that if your goal is to host the docs on a server anyway.

the goal is improved experience with both private and public viewing of Zig docs, so yes the local experience is also important

all but 2 of the protobuf links are outdated and 1 of them is just a C library packaged with zig, it wouldnt make any sense for them to host docs.

it was just a personal example from my own experience, do you have data showing that Zig docs are more common than I am illustrating?

[rohlem]

ideally we could generate docs without compiling

related: #3028