Zig: generate html documentation for a library

[andrewrk]

In progress!

[tiehuis]

Started something preliminary here https://github.com/tiehuis/zig-docgen.

The idea right now is to generate some intermediate form (JSON) and pass that to some existing document generator. Working on writing the tokenizer in zig and a simplistic parser so may have some overlap with #89 eventually.

[andrewrk]

Exciting!

I envision documentation generation as automatically happening as part of the normal build process. Rust's generated documentation looks great and has a usable search feature. I think doxygen is an example of what not to do.

Maybe as you mentioned, we get started on that self hosted compiler so we can do this feature in userland. As long as we keep the C++ implementation able to build the zig implementation, the bootstrapping process is simple enough.

Also related is the compiler outputting in some way data that is useful for IDEs such as an AST or a type table or something. @thejoshwolfe knows more about the requirements there.

[andrewrk]

I'm starting to think it might make sense to go ahead and implement this in stage1:

• Prototypes reveal issues so that when doing the final implementation, we can make better informed design decisions. For example, if I hadn't prototyped copy-elision in stage1, it would have been a much lower quality implementation in self-hosted.
• We really need this feature. It's been too long without it already.
• Much of the work can be reused, such as the html and js.

[andrewrk]

Progress of this is now underway:

• [x] proof of concept
• [x] -fgenerate-docs to generate doc/ directory
• [x] docs/ (plural) rename
• [ ] ~integrate with zig build system~ #3405
• [x] render functions
• [ ] ~render other types~ #3404
• [x] type aware functions with error sets etc
• [x] implement search
• [x] add the concept of pub to semantic analysis dump
• [x] add stage1 parsing for doc comments
• [x] add the concept of canonical paths to a package
• [x] add the concept of canonical paths to a decl
• [ ] ~implement source listings with links back to docs~ #3403
• [x] add to semantic analysis dump references from generic functions to all the instantiated functions
• [x] html/css style improvements
• [x] keyboard shortcut helper dialog box
• [x] add hyperlinks to search results
• [x] struct fields

[jayschwa]

generate doc/ directory

FYI, GitHub has an option to serve HTML from the /docs (plural) directory.

[andrewrk]

FYI, GitHub has an option to serve HTML from the /docs (plural) directory.

Hmm, that's a pretty good reason to change it.

[andrewrk]

3406 #3407 #3408 #3409