Contributing documentation?

Brainstorming
1

Hey everyone, I got some experience working with the build system and wanted to contribute some documentation. I opened an issue to gauge interest in contributions, but never got a response: Additional build system documentation? · Issue #561 · ziglang/www.ziglang.org · GitHub

Is this the expected way to contribute, or am I missing something?

This first contribution is pretty small, but I was thinking of contributing more to the build system docs (e.g. writing out some of the explanations from the video that @kristoff made about it). I don’t want to spend time on it if it won’t be reviewed.

9 Likes
2

post it here
for me zig build still is black magic
thanks in advance

1 Like
3

Please do post it here. We have A Doc’s section and are looking for more additions to it.

1 Like
4

Here is the docs op wants to contribute, yoinked from the pr, that mentioned the issue, that they linked.

The Build Graph

We previously mentioned that the Zig build system models the build process as a DAG.

We will now discuss how this graph is constructed.

The core of this graph is std.Build.Step.

Every Step has a name and a list of dependencies, which are other Steps.

These Steps and the dependencies between them form the build graph.

The most basic way to create a new step is via the std.Build.step method.

This method creates a new standalone Step, meaning that it does not depend on any other Steps, and no other Steps depend on it.

You can add this step as a dependency of another step via the dependent step’s std.Build.Step.dependOn method.

You can also use dependOn to add dependencies to this step.

The std.Build.step method is generic in the sense that it’s agnostic to the contents and purpose of the Step that it creates.

However, in many cases there are helper methods to create Steps for various purposes.

For instance, the std.Build.installArtifact method creates a std.Build.Step.InstallArtifact and adds its step as a dependency of the top-level “install” step.

This ensures that some artifact will be installed to zig-out when zig build install or zig build (since “install” is the default step) are run.

It’s also possible to use the std.Build.addInstallArtifact method to create an InstallArtifact step that isn’t tied to the top-level “install” step, which gives you the ability to install an artifact as part of some other build step.

Another helper method to be aware of is std.Build.addExecutable, which was shown in the previous section.

This helper method creates a std.Build.Step.Compile, which is one of the arguments required by the std.Build.installArtifact method.

This is why in examples you’ll frequently see both addExecutable and installArtifact.

This may give you the impression that “executable” and “artifact” are different kinds of entities that you need to know about in order to write your build.zig, but it really just boils down to Steps.

2 Likes
5

Thanks for pasting that in here, I’ve added it to the build docs in the Docs section.

I checked out that Docs section (which I didn’t know existed, actually, it’s not very prominent in the sidebar on desktop), and I’m confused why these build docs live here rather than on ziglang.org.

My original post was asking what the process is for contributing to the documentation on ziglang.org, and the fact that we have docs on ziggit.dev just kind of confuses me even more :sweat_smile: . Is it not welcome to contribute there, are there other plans for that documentation, does that repo not get many eyes on it, or something else?

6

The docs on Ziggit are just our own attempt at filling some of the holes in the official documentation.

I think contributions are welcome, I assume the core team is just very busy with the things they are working on, so it may take a while until somebody looks at these issues/prs regarding documentation improvements.

7

Gotcha, I’m kind of the “documentation guy” at work so I’m happy to pitch in. If there’s no real structure around that, I’m happy to provide some! I worked on the Nix documentation (I know, that’s why I worked on them :sweat_smile: ) and led a little team there for a while. Happy to plug away on my own or put a small team together dedicated to documentation.

One thing I’m itching to do is generate a Dash/Zeal docset so my ADHD-addled brain can ping back and forth between my editor and the std docs at lightning speed lol

3 Likes
8

A dash/zeal docset for zig would be very nice to have!

1 Like