-
-
Notifications
You must be signed in to change notification settings - Fork 2.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
generate html documentation for a library #21
Comments
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. |
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. |
I'm starting to think it might make sense to go ahead and implement this in stage1:
|
This commit adds -fdump-analysis which creates a `$NAME-analysis.json` file with all of the finished semantic analysis that the stage1 compiler produced. It contains types, packages, declarations, and files. This is an initial implementation; some data will be missing. However it's easy to improve the implementation, which is in `src/dump_analysis.cpp`. The next step for #21 will be to create Zig code which parses this json file and creates user-facing HTML documentation. This feature has other uses, however; for example, it could be used for IDE integration features until the self-hosted compiler is available.
This commit adds `-fgenerate-docs` CLI option, and it outputs: * doc/index.html * doc/data.js * doc/main.js In this strategy, we have 1 static html page and 1 static javascript file, which loads the semantic analysis dump directly and renders it using dom manipulation. Currently, all it does is list the declarations. But there is a lot more data available to work with. The next step would be making the declarations hyperlinks, and handling page navigation. Another strategy would be to generate a static site with no javascript, based on the semantic analysis dump that zig now provides. I invite the Zig community to take on such a project. However this version which heavily relies on javascript will also be a direction explored. I also welcome contributors to improve the html, css, and javascript of what this commit started, as well as whatever improvements are necessary to the static analysis dumping code to provide more information. See #21.
This commit adds `-fgenerate-docs` CLI option, and it outputs: * doc/index.html * doc/data.js * doc/main.js In this strategy, we have 1 static html page and 1 static javascript file, which loads the semantic analysis dump directly and renders it using dom manipulation. Currently, all it does is list the declarations. But there is a lot more data available to work with. The next step would be making the declarations hyperlinks, and handling page navigation. Another strategy would be to generate a static site with no javascript, based on the semantic analysis dump that zig now provides. I invite the Zig community to take on such a project. However this version which heavily relies on javascript will also be a direction explored. I also welcome contributors to improve the html, css, and javascript of what this commit started, as well as whatever improvements are necessary to the static analysis dumping code to provide more information. See #21.
Progress of this is now underway:
|
FYI, GitHub has an option to serve HTML from the |
Hmm, that's a pretty good reason to change it. |
This appears to be more of a standard directory name. See #21
Currently only ships the langsec.html file. Further documentation will be generated in future releases, see: ziglang/zig#21
Will there also be a feature to show docs on the command-line, like |
In progress!
The text was updated successfully, but these errors were encountered: