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

proof of concept of stage1 doc generation #3379

Merged
merged 1 commit into from
Oct 5, 2019
Merged

proof of concept of stage1 doc generation #3379

merged 1 commit into from
Oct 5, 2019

Conversation

andrewrk
Copy link
Member

@andrewrk andrewrk commented Oct 4, 2019

This commit adds -fgenerate-docs CLI option, and it outputs:

  • doc/index.html
  • doc/data.js
  • doc/main.js

It works without a server, e.g. you can use the file:/// URL in a web browser.

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.

To see this for the standard library, try this:

./zig test ../lib/std/std.zig -fgenerate-docs --output-dir zig-cache/

Then have a look at zig-cache/doc/index.html.

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 merged commit dca6e74 into master Oct 5, 2019
@andrewrk andrewrk deleted the mvp-doc-gen branch October 5, 2019 06:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant