Change emit-docs?

[JPL]

Good morning,
I read that you can no longer do emit-docs = .emit

we are talking about Step.Compile.getEmittedDocs but what does that mean please

//Build step to generate docs:  

    const docs = b.addTest(.{
    .name = "Gencurs",
    .root_source_file = .{ .path = "./Gencurs.zig" },
    .target = target,
    .optimize = optimize,

    });



    docs.addIncludePath(.{.path = "./lib/"});
    docs.linkLibC();
    docs.addObjectFile(.{.cwd_relative = "/usr/lib/libpcre2-posix.so"});
    docs.addModule("dds"   , dds);
    docs.addModule("cursed", cursed);
    docs.addModule("utils" , utils);
    docs.addModule("forms" , forms);
    docs.addModule("grid"  , grid);
    docs.addModule("match" , match);
    docs.addModule("mdlPanel" , mdlPanel);
    docs.addModule("mdlObjet" , mdlObjet);
    
    beug ????? 
    docs.emit_docs = .emit;


    
    
    const docs_step = b.step("docs", "Generate docs");
    docs_step.dependOn(&docs.step);

could we have an example to generate documentation.

doc.emit_docs=.emit is no longer functional

and what is it replaced by? please

[JPL]

zig build-obj -femit-docs myprogram.zig -->OK single program not import

zig build-obj -femit-docs --build-file buildmyprograme.zig → very bad buidlfile

zig build docs --build-file buildmyprograme.zig → beug and

docs.emit_docs = .emit;

zig build-obj -femit-docs myprogram.zig → bad because of import dependencies

[JPL]

Hello
I found while digging through the bug requests

    //Build step to generate docs:  
  
    const docs = b.addTest(.{
    .name = "Gencurs",
    .root_source_file = .{ .path = "./Gencurs.zig" },
    //.target = target,
    //.optimize = optimize,
    });



    docs.addIncludePath(.{.path = "./lib/"});
    docs.linkLibC();
    docs.addObjectFile(.{.cwd_relative = "/usr/lib/libpcre2-posix.so"});
    docs.addModule("dds"   , dds);
    docs.addModule("cursed", cursed);
    docs.addModule("utils" , utils);
    docs.addModule("forms" , forms);
    docs.addModule("grid"  , grid);
    docs.addModule("match" , match);
    docs.addModule("mdlPanel" , mdlPanel);
    docs.addModule("mdlObjet" , mdlObjet);
    
    const install_docs = b.addInstallDirectory(.{
        .source_dir = docs.getEmittedDocs(),
        .install_dir = .prefix,
        .install_subdir = "Doc_Gencurs",   // exemple
    });

    
    const docs_step = b.step("docs", "Generate docs");
    docs_step.dependOn(&install_docs.step);
    docs_step.dependOn(&docs.step);

[mlugg]

(JPL’s answer is correct, but I just thought I’d add a bit of detail here)

As the release notes mention, getEmittedDocs is the new method of accessing generated documentation. If that function is used to get a LazyPath, the build system will automatically trigger documentation generation to the returned directory.

Let’s say you have a std.Build.Step.Compile named lib, and you want to generate documentation for it and put it in the doc/ directory in the install prefix (zig-out/ by default). We’ll do this using an InstallDir step, which copies a directory of files to the installation prefix. Assuming your *std.Build is named b, your code would look like this:

b.installDirectory(.{
    .source_dir = lib.getEmittedDocs(),
    .install_dir = .prefix,
    .install_subdir = "doc",
});

The idea here is that we’re separating documentation generation from installation: the former is handled by getEmittedDocs and the latter by the InstallDir step. source_dir is telling the step what it is we want to copy (in this case the documentation directory); install_dir is the root path we’re going into (.prefix means the installation prefix); and install_subdir is the string subdir we want to go to (in this case "doc"). So this will generate the documentation for lib and copy it into to zig-out/doc/ by default.

Hope this explanation made sense

[dude_the_builder]

This is not working for me (zig v0.13 dev)
build.zig:

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const lib = b.addStaticLibrary(.{
        .name = "foo",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    b.installArtifact(lib);

    const docs = b.addInstallDirectory(.{
        .source_dir = lib.getEmittedDocs(),
        .install_dir = .prefix,
        .install_subdir = "docs",
    });
    b.getInstallStep().dependOn(&docs.step);
}

src/main.zig

//! Simple little add library.

const std = @import("std");

/// This function adds `b` to `a` and returns the result.
pub fn add(a: i32, b: i32) i32 {
    return a + b;
}

test add {
    try std.testing.expectEqual(10, add(3, 7));
}

zig-out/docs dir is generated with files in it, but loading in the browser yields:

[00JCIV00]

Edit: This message isn’t quite correct. Please look at @ianprime0509’s message below.

I believe this is because the static library name needs to match the name of the file (so .name = "main" vs your current .name = "foo") for autodocs to properly generate docs for it. OR you can name your Library’s root file root.zig.

@ianprime0509 did some work on this front a few weeks back to improve the experience. That said, I admit it can be a little confusing if you don’t know these rules. I may also be a little off base if “main.zig” is also intended to work, but I think I remember that not being the case.

[ianprime0509]

Hmm, for what it’s worth, this example project works fine for me (Zig 0.13.0-dev.3753+20b9b54e6):

There are a few things which I think are important to note for users of the new Autodoc, especially those who may have used the original implementation. Hopefully one of these will help address the issue you’re seeing.

1. It is required to use a local HTTP server to serve the docs files.

   The old Autodoc worked fine by just opening up index.html in a browser, since nothing was being fetched dynamically (just CSS and JS files included in the usual way). But the new implementation has to fetch a Wasm binary and sources.tar containing the source files, which does not work with file:// URLs due to CORS restrictions.

   Probably the easiest way to get this set up is to run python -m http.server -d path/to/docs, since many people probably already have Python installed. Having this functionality bundled into Zig would be nice (it’s implemented for the standard library docs in zig std, but not yet exposed for user projects).

2. Optimal documentation organization requires adhering to some project structure constraints.

   This is what @00JCIV00 was referring to: the first thing that shows up when you navigate to the docs is the root source file as determined by looking for a file named your-module-name.zig (in this case, foo.zig) or root.zig. If no such file exists, it’ll use the first file in the sources.tar (which is effectively arbitrary).

   However, regardless of this, all the documentation will still be accessible; this only affects what you first see when you load the main page. In this simple example, it doesn’t matter since there’s only one source file anyway. But in a larger project, if you don’t follow this convention, the main page will probably just be some random file in the project and not the root file you’re expecting.

   Also, the sources.tar creation bundles everything in the directory of the root source file, which means if you don’t put your source files under a src directory, you’ll end up with build.zig and other stuff included in the tarball.

3. The URL hash structure has changed.

   This is really only relevant for those with existing bookmarks to Autodoc. For example, https://ziglang.org/documentation/master/std/#A;std doesn’t work. The equivalent URL in the new implementation is https://ziglang.org/documentation/master/std/#std

[00JCIV00]

Appreciate you clarifying.

[dude_the_builder]

Thanks for the details. Really good to know. Unfortunately, I still get the same results. I renamed src/main.zig to src/foo.zig and made the corresponding change in build.zig.

Env info:

❯ zig version
0.13.0-dev.46+3648d7df1

❯ python3 -m http.server -d zig-out/docs 8080
Serving HTTP on :: port 8080 (http://[::]:8080/) ...
::1 - - [02/May/2024 19:35:25] "GET / HTTP/1.1" 200 -
::1 - - [02/May/2024 19:35:25] "GET /main.js HTTP/1.1" 200 -
::1 - - [02/May/2024 19:35:25] "GET /main.wasm HTTP/1.1" 200 -
::1 - - [02/May/2024 19:35:25] "GET /sources.tar HTTP/1.1" 200 -

FS tree:

.
├── build.zig
├── build.zig.zon
├── src
│   └── foo.zig
└── zig-out
    ├── docs
    │   ├── index.html
    │   ├── main.js
    │   ├── main.wasm
    │   └── sources.tar
    └── lib
        └── libfoo.a

5 directories, 8 files

Chrome dev tools confirm loading successfuly:

[dude_the_builder]

Stop the press! Now it works. For some weird reason, the URI in the address bar I kept tring to reload was http://localhost:8080/#src/foo/root.zig. After leaving it at just http://localhost:8080/ it works fine. It seems that the previous module name mix-up pointed the browser to that URI, and from that point on I just kept reloading the same address.

One last question: I was expecting to see the doc test for add; why isn’t it part of the docs page?

EDIT: Never mind, I just clicked on the add link and have seen everything gloriously displayed in one place. Awesome! Thanks again guys.

[adria]

We will definitely need a video explanation about this!

[adria]

I was trying to generate the documentation for a library, and if I add “type aliases” that won’t work:

Example:

pub const Point = @import("point.zig").Point2d(f32);

I would expect that, when I go to the definition of Point, Point2d would be underlined, but it isn’t.
I need to just import it without doing the specialization part, that is:

pub const Point = @import("point.zig").Point2d;

Or maybe create a docs.zig where I import all types from all files. A shame that a docs.zig containing this doesn’t generate documentation:

pub usingnamespace @import("point.zig");

[JPL]

Version 0.12.0

	const docs = b.addTest(.{
	.name = "Exemple",
	.root_source_file = .{ .path = "./Exemple.zig" },
	.target = target,
	.optimize = optimize,
	});
	
	docs.addIncludePath(.{.path = "./lib/"});
	docs .linkLibC();
	docs.addObjectFile(.{.cwd_relative = "/usr/lib/libpcre2-posix.so"});

	docs.root_module.addImport("cursed", cursed);

	docs.root_module.addImport("utils", utils);

	docs.root_module.addImport("match", match);
	
	docs.root_module.addImport("forms", forms);
	
	docs.root_module.addImport("grid" , grid);
	
	docs.root_module.addImport("menu" , menu);
	
	docs.root_module.addImport("callpgm" , callpgm);


	
	const install_docs = b.addInstallDirectory(.{
		.source_dir = docs.getEmittedDocs(),
		.install_dir = .prefix,
		.install_subdir = "../Docs_Exemple",
	});
	const docs_step = b.step("docs", "Generate docs");
	docs_step.dependOn(&install_docs.step);
	docs_step.dependOn(&docs .step);