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.

Sign up for GitHub

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

Jump to bottom

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
0.6.0

Comments

@andrewrk
Copy link
Member

andrewrk commented Dec 11, 2015 •
edited
Loading

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
Closed
12 tasks
@andrewrk andrewrk added this to the 0.2.0 milestone Apr 3, 2017
andrewrk referenced this issue in AndreaOrru/zen May 3, 2017
@AndreaOrru
Doubly linked list. Preliminary thread and process structures.
3098225
@tiehuis
Copy link
Member

tiehuis commented Sep 7, 2017 •
edited
Loading

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 andrewrk modified the milestones: 0.2.0, 0.3.0 Jan 3, 2018
@andrewrk andrewrk modified the milestones: 0.3.0, 0.4.0 Feb 28, 2018
@andrewrk andrewrk mentioned this issue Apr 29, 2018
Closed
@andrewrk andrewrk mentioned this issue Jul 11, 2018
Closed
8 tasks
@mdsteele mdsteele mentioned this issue Jul 30, 2018
Closed
@andrewrk andrewrk mentioned this issue Aug 6, 2018
Closed
@andrewrk andrewrk mentioned this issue Oct 8, 2018
Merged
@andrewrk
Copy link
Member Author

andrewrk commented Nov 13, 2018 •
edited
Loading

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
@hryx hryx mentioned this issue Nov 24, 2018
Closed
@andrewrk andrewrk modified the milestones: 0.4.0, 0.5.0 Feb 2, 2019
@benjif benjif mentioned this issue May 23, 2019
Closed
@hryx hryx mentioned this issue Jun 28, 2019
Closed
@ghost ghost mentioned this issue Jul 14, 2019
Closed
@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
@andrewrk
add -fdump-analysis to dump type information to json
59ac7b9 
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 andrewrk mentioned this issue Oct 3, 2019
Merged
andrewrk added a commit that referenced this issue Oct 4, 2019
@andrewrk
proof of concept of stage1 doc generation
1c1e1c7 
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 andrewrk mentioned this issue Oct 4, 2019
Merged
andrewrk added a commit that referenced this issue Oct 5, 2019
@andrewrk
proof of concept of stage1 doc generation
dca6e74 
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 •
edited
Loading

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
Sponsor 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 added a commit that referenced this issue Oct 7, 2019
@andrewrk
generated docs: docs/ instead of doc/
86171af 
This appears to be more of a standard directory name.

See #21
This was referenced Oct 8, 2019
Closed
Closed
Closed
Open
@andrewrk
Copy link
Member Author

andrewrk commented Oct 8, 2019

#3406 #3407 #3408 #3409

@andrewrk andrewrk closed this as completed Oct 8, 2019
@mikdusan mikdusan mentioned this issue Jan 20, 2020
Closed
algitbot pushed a commit to alpinelinux/aports that referenced this issue Apr 14, 2020
@nmeum
testing/zig: add -doc subpackage
6838e81 
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
Assignees
No one assigned
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
Milestone
0.6.0
Development

No branches or pull requests
3 participants
@andrewrk @jayschwa @tiehuis