Skip to content
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

Closed
andrewrk opened this issue Dec 11, 2015 · 8 comments
Closed

generate html documentation for a library #21

andrewrk opened this issue Dec 11, 2015 · 8 comments
Labels
enhancement Solving this issue will likely involve adding new logic or components to the codebase. frontend Tokenization, parsing, AstGen, Sema, and Liveness. stage1 The process of building from source via WebAssembly and the C backend.
Milestone

Comments

@andrewrk
Copy link
Member

andrewrk commented Dec 11, 2015

In progress!

@andrewrk andrewrk added the enhancement Solving this issue will likely involve adding new logic or components to the codebase. label Dec 11, 2015
@andrewrk andrewrk mentioned this issue Oct 26, 2016
12 tasks
@andrewrk andrewrk added this to the 0.2.0 milestone Apr 3, 2017
@tiehuis
Copy link
Member

tiehuis commented Sep 7, 2017

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
Copy link
Member Author

andrewrk commented Sep 7, 2017

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
Copy link
Member Author

andrewrk commented Nov 13, 2018

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 andrewrk added frontend Tokenization, parsing, AstGen, Sema, and Liveness. stage1 The process of building from source via WebAssembly and the C backend. labels Nov 17, 2018
@andrewrk andrewrk modified the milestones: 0.4.0, 0.5.0 Feb 2, 2019
@andrewrk andrewrk modified the milestones: 0.5.0, 0.6.0 Aug 30, 2019
andrewrk added a commit that referenced this issue Oct 3, 2019
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.
andrewrk added a commit that referenced this issue Oct 4, 2019
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.
andrewrk added a commit that referenced this issue Oct 5, 2019
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.
@andrewrk
Copy link
Member Author

andrewrk commented Oct 5, 2019

Progress of this is now underway:

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

@jayschwa
Copy link
Contributor

jayschwa commented Oct 6, 2019

generate doc/ directory

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

@andrewrk
Copy link
Member Author

andrewrk commented Oct 6, 2019

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

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

@andrewrk
Copy link
Member Author

andrewrk commented Oct 8, 2019

#3406 #3407 #3408 #3409

@andrewrk andrewrk closed this as completed Oct 8, 2019
algitbot pushed a commit to alpinelinux/aports that referenced this issue Apr 14, 2020
Currently only ships the langsec.html file. Further documentation will
be generated in future releases, see: ziglang/zig#21
@ghost
Copy link

ghost commented Mar 25, 2022

Will there also be a feature to show docs on the command-line, like go doc? That's a feature I love having in Go, and really dislike the idea of documentation being only viewable through a web browser, especially for a low-level language.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Solving this issue will likely involve adding new logic or components to the codebase. frontend Tokenization, parsing, AstGen, Sema, and Liveness. stage1 The process of building from source via WebAssembly and the C backend.
Projects
None yet
Development

No branches or pull requests

3 participants