search

ballercat / walt

:zap: Walt is a JavaScript-like syntax for WebAssembly text format :zap:
https://ballercat.github.io/walt/
MIT License
4.64k stars 122 forks source link

Docs site integration #161

Closed konsumer closed 5 years ago

konsumer commented 5 years ago

Related #59

This integrates the new design into docs as a gatsby site, moves packages/walt-docs to packages/walt-explorer to prep for being built as a reusable react component, and includes the start of the API docs.

You can see it running here

Still todo for website:

coveralls commented 5 years ago

Pull Request Test Coverage Report for Build 193

Totals Coverage Status
Change from base Build 188: 0.0%
Covered Lines: 1896
Relevant Lines: 1896
💛 - Coveralls
ballercat commented 5 years ago

Very cool. I've been messing around with this branch to get the feel for the site setup. It takes some getting used to gatsbyjs but it's not terribly complex. I'm going to make some adjustments to the pages and documentation to get a better handle on it.

As far as pages themselves. I don't love the API documentation look/theme. It feels off to me. The fonts are a bit too large for example and the foreground content blends weirdly with the background. Code blocks also don't have clear boundaries. I prefer a cleaner look for reference documentation.

I'm going to tweak some things to get started and add some more JSDoc blocks in the meantime.

ballercat commented 5 years ago

I tried to push some updates but I can't seem to push to the PR branch.

konsumer commented 5 years ago

Sounds good. The main thing I changed from @matteocargnelutti's scss was using more generic selectors, so the css will work easily in markdown without needing special elements or classes. This PR could just be thought of as a start of the idea of a built doc-site, complete with deployment to ghpages, auto-doc generation.

I tried to keep it tidy by separating animations, base style (shared generic styles) and docs/landing for style specific to those sections. My goal was to keep as much static content as possible in markdown, so it can be easily edited, once we have locked in on a set of templates & style.

As a next step, after styles are setup, I recommend setting up CI that builds and publishes the site, so anyone with write access to repo can edit website by committing to it. This can be especially handy for things like editing the markdown files in src/pages directly, on github.

Gatsby has a lot of features that might not be initially apparent, like it builds a bunch of static SSR pages, but also hot-loads JS content in the background. It also has a pretty rich plugin ecosystem, so you can quickly add nice features (like in this setup: documentjs, server-side rendered prisma, auto-generated cache-manifest, and custom-components that can be inserted into markdown.)

konsumer commented 5 years ago

As for pushing to PR branch, it's a fork, so I can add you as a collaborator. Alternately, you could merge the branch and just put your commits after, on walt's master. I could also put it all on a branch, if that helps, but I think we might have the same situation.

konsumer commented 5 years ago

speaking of CI, there might be an issue with multiline comments. There were a bunch of comments like this:

/**
 * Some multi-line non-jsdoc comments
*/

/** triggers the documentjs parser to look at the comment, so I removed that from comments that didn't directly document exports, to tune the docs. I am noticing the build is now failing due to eslint errors, so we may have to do something to either make eslint ok with those, or documentjs ignore some comments. The documnentjs gatsby plugin doesn't really have any config, and /** is a pretty standard trigger for all document-generating systems (jsdoc, javadoc, phpdoc, etc) so it might make more sense to do the former.

konsumer commented 5 years ago

@ballercat I added you as a collaborator to my fork, so you can just try it out there, directly. You can also publish to the ghpages with npm run deploy

ballercat commented 5 years ago

@konsumer I'm still unable to push to your fork. Usually, the PRs are from non master branches so it might be the problem here. IIRC github has a setting to allow collaborations on branches when creating a PR that could also be it. I would like to make a few changes before merging this in. Also, are you making more changes to this (not sure from your comments)?

konsumer commented 5 years ago

I'm still unable to push to your fork.

Hmm, that seems odd. DId you check out from ssh or https?

IIRC github has a setting to allow collaborations on branches when creating a PR that could also be it.

I'm not sure I follow. Is there something I should do differently? I don't see any options about collaboration on PR creation, and I've never see PRs work this way. Again, if it's a big fuss, maybe just merge it to another branch (via cherry-pick, if you like,) and make your changes after.

Also, are you making more changes to this (not sure from your comments)?

Nope, I'm leaving it alone for now.

ballercat commented 5 years ago

Okay cool, I did not want to mess with this if you were still tweaking it. Thank you for your work!

I'm going to move it to a local branch for now so that we can wrap it up in a different PR later.