zig init: Add step to generate documentation#22690
zig init: Add step to generate documentation#22690sorairolake wants to merge 1 commit intoziglang:masterfrom
Conversation
sorairolake
force-pushed
the
add-doc-step
branch
from
76a96e0 to
c179c54
Compare
linusg
left a comment
linusg
left a comment
There was a problem hiding this comment.
LGTM with one more change.
| const install_docs = b.addInstallDirectory(.{ | ||
| .source_dir = docs_obj.getEmittedDocs(), | ||
| .install_dir = .prefix, | ||
| .install_subdir = "docs", |
There was a problem hiding this comment.
This is a bit of an odd choice of directory. Since this is zig init, I think we should try to encourage best practice. I'd expect something more like $prefix/share/doc/$name/html (the norm on Debian/Ubuntu at least).
| .install_subdir = "docs", | |
| .install_subdir = b.pathJoin(&.{ "share", "doc", ".NAME", "html" }), |
There was a problem hiding this comment.
Autodocs output is hardly something distros would want to install so I don't think it makes sense to follow distro conventions here. Much more likely that someone will view the files from a local zig-out/ or a CI system will copy them onto a static file server.
See also:
Lines 60 to 64 in cb8d7a8
There was a problem hiding this comment.
Autodocs output is hardly something distros would want to install
Hm, what makes you say that? I see an ocean of API docs in /usr/share/doc on my system, many of them in HTML form, and many of them generated from source code.
There was a problem hiding this comment.
Discoverability mostly - if it was a man page there is a tool that knows where to look for those. Windows back in the day had at least a chm viewer (which would be lovely for this now that I think about it!). If I have to manually dig around in some system directory where I may or may not find what I'm looking for I'll directly go to the nearest search engine instead.
Maybe I'm an outlier though 🙂
There was a problem hiding this comment.
I can't say I'm a frequent browser of /usr/share/doc myself... but my inclination is to follow established practice in distros when it comes to stuff like this.
@andrewrk any thoughts on this since you've done Debian packaging work?
| // This creates a `docs` step. It will be visible in the `zig build --help` | ||
| // menu, and can be selected like this: `zig build docs` | ||
| // This will generate the package documentation from the doc comments. | ||
| const docs_step = b.step("docs", "Build the package documentation"); |
There was a problem hiding this comment.
Is there actually a good reason why we want this to be its own named step, as opposed to just being part of b.getInstallStep()?
There was a problem hiding this comment.
Add a `docs` step to `build.zig` which `zig init` generates. This step will generate the package documentation from the doc comments. The generated package documentation can be viewed by running the following in the directory where it was generated: ```sh python -m http.server ``` Also, add doc comments and doctests to `add` function to provide an example of these.
sorairolake
force-pushed
the
add-doc-step
branch
from
42e658b to
f483866
Compare
4 participants
Add a
docsstep tobuild.zigwhichzig initgenerates. This step will generate the package documentation from the doc comments.The generated package documentation can be viewed by running the following in the directory where it was generated:
Also, add doc comments and doctests to
addfunction to provide an example of these.Closes #22644