Website ?

[matteocargnelutti]

Would you like some help with WALT's website ?
Even if the project pre-alpha, I think it could be nice to have a small website for the project, showcasing its features, its docs, etc.
If you think that's a good idea, I'd be happy to help.

[ballercat]

Hi!

I would absolutely accept PRs/help for a stand-alone website. I like your idea of a one-stop shop for docs and features.

I'm mostly focused on the compiler design/structure at this point in the project and probably for foreseeable future. What that means is I don't have a specific direction in mind for a Website, which means I would need someone to take ownership of the site as a stand-alone part of the project.

If you're willing to take on the responsibility of maintaining that piece of the project you will get my full support no doubt. I don't particularly know how much effort it would take, but I assume it's not negligible.

If you are more interested in more smaller, focused, incremental contributions that would work as well. As it stands right now the portions of the code pertaining to docs and the site/explorer page are basically up for grabs.

[matteocargnelutti]

I'll have a bit of time in the coming months, but sadly not enough to help you with Walt's core.
But I really enjoy your project and think more people should hear about it : i'd like to help, hence my message.

So I'd be glad to help with the website and take the responsibility of it.

Maybe I can work on a first draft and come back here to see how it goes ?

[ballercat]

That's awesome; I appreciate the help.

I think a mock/up with a written list of what high-level changes, additions will be an excellent first step. The general idea of the direction, UI, color scheme and what you would like to use to power the site(static site generator?). We can save a bunch of time upfront if we are on the same page. I can help out with the UI/tech direction, once we have something written down.

[matteocargnelutti]

Yes, perfect, that was what I had in mind for a first draft.

I was also thinking of using a static site generator, with all the generated content delivered by GitHub pages.
Do you have any preference regarding the generator ?
I'm used to work with Flask + Flask-Static (as I am more of a Python guy initialy) with markdown files for the content base, but I don't mind using something else.

Alright, let's keep in touch.
I have a busy week coming (moving-in in Boston ;-)), I'll start working on it asap.
Glad I can help.

[ballercat]

Welcome to the neighborhood! Boston is a great town.

[ballercat]

Hey, I totally spaced about the generator preference question. I would appreciate if we stick with JS based ones if possible. Since I'd like to be able to get in there and mess with the code if I have to. I think Gatsby looks promising.

I could be convinced of the alternative if it's objectively better though.

[matteocargnelutti]

Hi !

Totaly makes sense to use a JS-based generator : I'll take a look at Gatsby and other JS-based generators.
I'm sorry I can't do much more this week (yep, I'm moving in right during the snow storm xD ...).
Let's keep in touch,

[matteocargnelutti]

Would you mind an Angular-based static site generator ?

[ballercat]

Honestly, I did not know one existed in Angular. My initial reaction is that I don't think so. What makes it a good candidate?

[matteocargnelutti]

There are a few :) !
I was just asking as I am reviewing a few options and came across a few nice solutions with Angular.

So, in your mind, should the website be a single page app ?

[ballercat]

I don't have a particular vision for the site, SPA seems like a nice-to-have, but not a necessity. Plus we could make a React Router SPA in like 10 minutes. But honestly, if you think it makes sense and it's something you can get done without it being a pain for you then yeah go for it.

I don't love Angular though; if I were choosing between Angular based site vs. a Python static site, I'd pick Python hands down. I'd rather brush up on my python skills instead of learning Angular lol.

[matteocargnelutti]

Lol I think we're on the same page ;-) (maybe not for the Angular part, though).

When you suggested Gatsby, I wondered if you had a vision for the website involving React (since it relies on React).
From my perspective, as it is a simple features + demo + docs simple website, I don't really see the point of going single-page.

So, regarding the generator, I'd go with something dead simple like Hexo (https://hexo.io/) or Metalsmith (http://www.metalsmith.io/).

For the rest, I'm working on it asap.
Enjoy the snow :) ...

[ballercat]

Simple is good, I heard about both of those.

I think I recommended Gatsby because it's the new hotness.

[iddan]

I highly suggest Gatsby - it's been a blast to develop with it

[matteocargnelutti]

Hi there,

Sorry it took so long : I guess moving in a new country / city during a "bomb cyclone" is more complicated than I thought.

Mockups :

Here are two quick mockups for the website.

First, the landing page, that explains in a few words what Walt is.

Then, the docs pages :

Each doc page would include links to the next section at their bottom.

So, as you can see, a very simple layout that I imagine as responsive.

Static-site generator :

I have taken a look at Gatsby JS, Hexo and Metalsmith, and I would choose Metalsmith (http://www.metalsmith.io/) , as it is (I think) the simplest way to generate a website from markdown documents via JS.
It is very simple to learn and use which makes it a good candidate in my opinion as it allows more people to contribute to the website without having to face a steep learning curve to understand the technology behind it.

Contents:

Here is a first list of contents I think would be needed in the docs :

• About Walt (basicaly, the github introduction)
• Setup
• Hello World
• Syntax
• In depth (the more detailed contents from the wiki about Walt inner machinery)
• Contributing

That's it for the first quick draft, let's discuss about all that :)

PS : Don't mind the ugly Comic Sans, I made the mockups with Balsamiq ;-)

[ballercat]

Hey,

First of all, this is awesome. I like the extras you added, the beaker and the "Walt does all the chemistry" details, it's a nice touch. The compact layout works well; I think this is the right direction to take.

I have not used metalsmith, but I do know of other Engineers whos judgment I trust and have enjoyed using it. So let's use metalsmith, I think it will work well for our use-case.

I like the individual pages you proposed, let's go with that. As far as content I think I'll need to dedicate a fair amount of time to fill in all the documentation so that will be an ongoing effort. I would like to crowdsource the docs, but it might not be possible at this stage(I'll just need to write down most of this).

For next steps, we should move forward with an MVP of the site. Let's figure out how the Markdown files themselves should look and what file/folder structure we would need to work with metalsmith. Once we have that, we can put in stubs for all the pages without content and fill those in via individual PRs!

Again, this is an excellent first step. I'm pretty excited to see the working product. Thank you so much!

[matteocargnelutti]

Hi,

Glad you like it :) let's do this !

If possible, I'd rather work first on the basic templates, and then on the machinery : would that work for you ?
How shall we proceed ? Maybe I could create my own repository and we migrate it later, when appropriate ?

If that works for you, I'll strat tomorrow.

[ballercat]

Sure, I'm okay with you doing the work in another repo if that makes it easier for you.

[matteocargnelutti]

Hi there,

There's been some progress :
You can check the first draft of the landing page template on the project's repo > https://github.com/matteocargnelutti/walt-website (just clone it and go in draft / template / landing).

Here's a video of the expected behaviour : https://we.tl/w7TUaB5kZR

So it is obviously a first draft, just wanted to have your feedback on the layout in general.

Have a nice day,
Matteo.

[matteocargnelutti]

PS : "Docs" template draft ready too :).

[ballercat]

Hey, I checked it out. Sorry, it took me a bit to respond but work has been taking up much of my time.

Nice work, I have a few comments so far.

I like the layout of the landing page overall, I don't like the rounded corners on the header and footer in full desktop mode though. I think the original mock-ups looked better because of that.

For the docs, I'd like to keep it simpler. I don't think coloring the headers is a good direction. We should keep the emphasis to bold text and headings only. Maybe with subtle coloring for headers. Most docs you want to just get in and get out, we don't need to add too much treatment.

Also, about the nav on the right-hand side. I tried it and I don't love it. I think if we are going to have a nav it should be static on either side of the content. It's just better to let users jump through sections quickly, and maybe even have everything a single scroll-able page with jump-able headings.

[matteocargnelutti]

Hi there,

Thanks for the feedback ! No worries, I do understand that you have a lot of work.

I agree on most points : I've made a quick update to both templates.
I got rid of the rounded corners : I tried it as a reference to Walt's hat ;-). I agree it was a bit too much.

For the docs, I tried something different, with a static menu on the side, a smaller header and the focus on the content . On mobile, the nav slides out and "grows" a handle.

Let me know :)
Matteo.

[matteocargnelutti]

Hi there,

I wondered if you had the opportunity to check the updated templates ?
Have a nice day,
Matteo.

[ballercat]

Hey!

I did look at them. I totally spaced on getting back to you. I have a couple of notes.

Landing page

• We should probably scale down the top header part of the landing page, to not take up 100% of the screen real-estate, seems a bit empty. Not a huge deal though. I think an improvement to the empty space might be a top-level nav-bar like thing(same blue color) with a couple of links like, docs, GitHub and Gitter chat.
• I'd like to see the landing page with a bit of code on it after the initial pitch of what Walt is/does. Followed by the get started footer etc., I think that would flow nicely.

Docs

• I think the background color is a bit too dark. I think it should be lighter. A lighter background would work better with a lot of text on the page & code blocks.
• I don't love the blue background for headers, IMO these should be plain text h1s.
• I think you should add a code block to some of these so that we can see how it looks.
• For whatever reason, the side-nav is just not appealing to me visually. One alternative could be a top-nav link to a docs landing page. Where the landing page has a plain TOC type list on it. Maybe it's the separators that are not looking too good to me, I'm not sure. A top nav would also be consistent with my suggestion for the landing page.

My general opinion on docs part is to keep it rather plain text-y with few color treatments. Mostly based on my own preferences. For reference here are the elm-lang docs http://elm-lang.org/docs which are sort of what I'm describing.

Sorry for taking so long to get back, I looked at it a while ago and forgot to write this down. We should start thinking about implementing this stuff via github pages soon!

[matteocargnelutti]

Hi Arthur,

I made a few edits on the templates : could you check it out when you have time, just to be sure i'm headed in the right direction ?
I tried a few things.

For the docs part, we could get rid of the whole blue bar on the top, replace it with plain text and put a black logo.

Cheers,
Matteo

[ballercat]

I like the direction, the plainer text for documentation works well IMO.

Feel free to try different treatments for the bar/navigation! The only other suggestion I have is that we should have a clearer separation between documentation text and code blocks via a different background, like more traditional code blocks on the web.

[matteocargnelutti]

Ok then :) !
I updated the templates. For the docs I tried something even "leaner".
Let me know.
Matteo.

[ballercat]

Those code blocks look great. Let's run with this setup for the body of the docs.

For the header, I don't see the logo.

[matteocargnelutti]

Really ? Have you cleared your cache ?

[ballercat]

Yeah it worked after a refresh. Looks good, notbad.jpeg

[matteocargnelutti]

Hi there !

Sorry it took so long : I had less free time than I first expected !

I ended up building my own generator for the website, for various reasons :
I started using Metalsmith, but had to use different plugins and build my own to achieve what I needed. I figured that it could be problematic in the future, for example if someone else wanted to contribute to the website.

So I built my own script, which I purposely put in a single JavaScript file and made as simple as possible, so anyone that knows a bit of JavaScript can contribute to the website in the future. (see : https://github.com/matteocargnelutti/walt-website/tree/master/src)

Here is the current version of the website running :
https://matteocargnelutti.github.io/walt-website/
There is still work to do on it of course.

And the repository, with the sources, the build script and the appropriate Readme : https://github.com/matteocargnelutti/walt-website

If that works for you, I think it's time to move the repository and work on the details, the contents, etc :)
Let me know,

Cheers,
Matteo.

[ballercat]

Hi there.

I'm going to level with you and say that I feel strongly about not maintaining a custom docs/site builder. However, I do agree with you that it'll be more difficult to gain additional contributions to a site if it's difficult to setup and requires an additional plugin for every custom feature. At the same time spinning up a custom site builder will just end up making it difficult to iterate and gain new contributions, so it's counterproductive to these goals.

So how do we reconcile these issues with our needs?

Here is what I propose.

It seems to me that there are two completely separate goals. Website and documentation. Doing both with the same tools is challenging and creates more issues than it solves. So, let's just do the two separately.

Let's move forward with the site

Instead of spinning up an additional site builder let's use the tools which are pretty good at making websites already. React + Webpack. Good news is I already have all the groundwork ready for running such a site for the Explorer/Playground and it builds into a github.io page. You have a pretty good template for the homepage, let's use that! But let's port it to React, this part should be trivial. I also have asset loading setup in the walt-docs repo which should help to port over any CSS you might have as well.

Go ahead and do that, make a PR with the site, move the playground to a separate page which we will link to from the homepage.

This will both make it easy to maintain and allow for easy contributions.

Let's ditch handcrafted docs

For documentation itself, let's use git-book. It's a pretty standard no-nonsense documentation builder, and more or less an industry standard, lots of Frontend projects use it already. It won't look like the site itself but I believe docs =/= website anyway. We can do that as a separate PR and just make the docs links as a TODO for now.

I think this should be a solid plan going forward, what do you think?

[matteocargnelutti]

Hi there,

Thanks for the feedback !
I do understand your point for the most part.
However, for different reasons, I don't see myself working in the direction you chose, sorry about that.

Please feel free to use everything you need from my repo :) ! I hope it helped a bit.

I hope your project will get the attention it deserves in the coming months,
Keep up the good work.

Cheers,
Matteo.

[ballercat]

Sorry to hear that, thanks for the help!

[JobLeonard]

Hey, sorry to bring this up but I find it really sad how this thread ended. I may sound a bit antagonistic below, and I apologise for that, but I honestly find the whole dynamic a bit upsetting.

@matteocargnelutti's last demo looked really good IMO. And I don't just mean the design itself, I mean the implementation too. Look at how lean this is under the hood:

And it even works when I disable JavaScript and external fonts using uMatrix! (except for syntax highlighting, since it requires prism.js)

This is a really clean, gracefully degradating, well designed website, which must have taken quite a bit of effort to craft.

Showing a bit more explicit appreciation for the thought and the love that Matteo put into this would have been appropriate, I think.

I'm sure you didn't intend to sound like this, bc, but a sentence like "let's use the tools which are pretty good at making websites already" sounds like his script isn't good at that, or something like "and it builds into a github.io page" implies his site doesn't (it builds to a static site, making that work as a github.io page is as trivial as pointing the build to the right output directory)

I also am a bit sad that Matteo didn't really explain what his ideas of what the best approach to building a website for Walt is, and how to achieve that. Other than that he kept his build script minimal and clean to make it easy for others to modify it.

I'm going to level with you and say that I feel strongly about not maintaining a custom docs/site builder.(...) At the same time spinning up a custom site builder will just end up making it difficult to iterate and gain new contributions, so it's counterproductive to these goals.

Is this true though? I understand that you feel strongly about this, but this isn't an everything-from-scratch kind of thing that Matteo built. Looking at his script behind the custom website builder, we have a few hundred lines of well-commented, dead-simple JavaScript, essentially just a tiny Node.JS shim around SASS, mustache and MarkDown (and prismjs for the highlighter, but that's not really a concern of for contributors who write the MarkDown content)

const fs = require('fs');
const mustache = require('mustache');
const sass = require('node-sass');
const marked = require('marked');

There is an argument to be made that there is a much bigger chance of potential contributors being familiar with mustache, SASS, and MarkDown, than of them being up-to-date about how to deal with React+WebPack. The former three have stable APIs and are supported in just about any language that can render static HTML pages. Meanwhile, over at WebPack 4 we have a migration fiasco. And speaking purely from my own POV here: that leaves a bad taste in my mouth after I waited like half a year to migrate to from WebPack 2 to 3 because it was so badly handled.

It seems to me that there are two completely separate goals. Website and documentation. Doing both with the same tools is challenging and creates more issues than it solves.

Why is that a problem exactly? Documentation is also a website, just a specific form of it that can have an optimised interface. Looking over at Matteo's repo, he already split those two concerns with two templates.

Want to contribute to the landing page? It's just HTML with a bit of mustache. To me this seems simpler than React for contributors.

Want to add documentation? It's just a bunch of MarkDown files, you could even edit it in-line in GitHub. I don't know how gitbook compares here but I doubt you'll find many people scared off by MarkDown.

And even if there is a reasonable fear that this script will turn into a ball of mud, it is not immediately obvious why React+WebPack would be the right alternative. I'm not hating on the two, building a datavisualisation SPA with them has paid my bills for the last two years, but not every site needs to be an SPA that breaks the back-button for no good reason.

However, I do agree with you that it'll be more difficult to gain additional contributions to a site if it's difficult to setup and requires an additional plugin for every custom feature.

The React ecosystem is huge and has tons of off-the-shelf options, yes. But let's invoke YAGNI and ask: what features are needed that result in the Walt website requiring complicated interactive UI interfaces, which is where React really shines?

The Walt Explorer is obvious, being an interactive coding playground (by the way, I just noticed that the explorer is currently not minified in production - it's a 4.57 MiB large JavaScript file). What else? Since we can't predict the future, I figure that taking a look at all the other language sites out there and see what they consider needed in practice might help:

http://elm-lang.org/

https://golang.org/

https://www.rust-lang.org/

https://nim-lang.org/

http://www.typescriptlang.org/

Ok, well... other than some sites having a coding playgrounds here and there, I still got nothing (also, Elm is the only one of these sites that breaks without JavaScript and it has very little reason to need that).

If the rest of the Walt site will end up pretty static, which looks likely based on other programming language websites, I don't see the point of adding the overhead of React (both in terms of development and deployment), when a static HTML page would suffice, load nearly instantly and not break my back button.

What I find especialy sad about all this is that Matteo's approach seemed to perfectly reflect Walt's minimalist philosophy towards WASM, except at the HTML level: let's avoid big tool-chains like metalsmith or React+WebPack, let's avoid doing everything through JavaScript. Let's just use simple basic modular technologies combined together in a clean fashion for a lean result that works as a static webpage. Maybe it's just me, but I find the idea of having Walt's website reflect the minimalist philosophy behind the language very appealing in a "practice what you preach" way.

[matteocargnelutti]

@JobLeonard Thanks for your post. I'm glad you understood what I wanted to achieve.

First, I'd like to point out that I have absolutely no hard feelings at all regarding how this has ended. I would be glad if the final project used parts of what I have done, but I wouldn't mind if it didn't. I still support WALT and I think @ballercat and the contributors are doing a great job.

I no longer have to explain my approach to this project since you did it so well, but, to answer your remark, here's a few words on why I didn't "push back" after @ballercat 's last feedback:
When @ballercat suggested to get rid of the documentation section and to use React+Webpack for what was remaining, a single homepage, I thought that our standpoints were too far away from one another to be reconciled. To be clear, I thought the solution proposed was over-engineered, could push away possible contributors in the future, and was not really futur-proof, for the reasons you exposed.
I didn't want to argue over this because, in the end, it's @ballercat 's project and I respect his opinion on how the website should be built even though I don't agree with it.

[ballercat]

Yeah, it's a bummer how things played out. I was excited about the concept.

From my perspective, I simply disagreed with building and maintaining a custom site generator when the tools for that already exist. I'll never have enough bandwidth to maintain the core of the project and a custom site generator. I never thought that the thing Matteo build was somehow bad or somehow not up to an implicit higher standard. I have no reason to.

Showing a bit more explicit appreciation for the thought and the love that Matteo put into this would have been appropriate, I think.

You know what, you're right. @matteocargnelutti the work you put into this was impressive and I should have been softer with my criticism of the approach. I should have spent more time to understand where you were coming from instead of shutting down the idea. It might have been possible to meet somewhere in the middle on this but now that opportunity is lost. That one is on me.

RE: Specifics of using React, Webpack

I won't go blow for blow with you on Webpack because you have some personal experience with it that differs from mine and we have different opinions on the matter, which is okay. It's fine to disagree about things. In the context of this project, it's only a tool. The challenges of converting to alternative versions or keeping the current version deployed up to date are of little importance as they are not real issues I face on such a simple setup.

The already existing configs and a running explorer site, the work is already done for this. I thought were a big plus. npm install && npm run start is all anyone needs to do to run the explorer page locally.

As for React, I don't think I suggested using React for all the documentation, but only for a single landing page. In retrospect, the entire landing page could have just been a static HTML file.

I borrowed the idea for git book from things like enzyme API documentation which is entirely based on MD files. Seems like a reasonable approach 😕

What I find especialy sad about all this is that Matteo's approach seemed to perfectly reflect Walt's minimalist philosophy towards WASM, except at the HTML level: let's avoid big tool-chains like metalsmith or React+WebPack, let's avoid doing everything through JavaScript. Let's just use simple basic modular technologies combined together in a clean fashion for a lean result that works as a static webpage. Maybe it's just me, but I find the idea of having Walt's website reflect the minimalist philosophy behind the language very appealing in a "practice what you preach" way.

The website design was and still is fantastic and I also found it appealing.

There were a ton of other issues you brought up and arguments you raised. Let me know if you want me to address anything else specifically.

[JobLeonard]

I'm really happy and relieved to see both of your positive replies to me dredging this up - I was a bit worried that I opened a can of worms.

From my perception, @ballercat wrote his post with the intention of "hey, this is how I feel, and here are my reasons why. Not to state that this is going to be, but to let others scrutinize and debate my views", but in his enthusiasm forgot to communicate the appreciation he has for @matteocargnelutti's work, who in turn might have felt too discouraged to argue the motivations behind his choices.

It was just a bit saddening to see two people who are clearly capable at what they do, and share a love for this project talk past each other like that.

mc: I didn't want to argue over this because, in the end, it's @ballercat 's project and I respect his opinion on how the website should be built even though I don't agree with it.

It's ballercat's baby and he makes the final choice, but my impression is that he actually wants constructive respectful discussions over disagreeing views. You might even convince him; I mean he can even admit on the internet that he should have shown more appreciation so anything's possible 😛

bc: It might have been possible to meet somewhere in the middle on this but now that opportunity is lost.

Don't say that! Now that this is cleared up, maybe there a compromise where Matteo can "do his thing" which still respects your vision for where to take the project.

(If I'm turning too much into a debating, mediating cheerleader for this project, let me know)

bc: There were a ton of other issues you brought up and arguments you raised. Let me know if you want me to address anything else specifically.

I pushed back a bit harder than necessary for Matteo to see that his hard work and reasoning behind his choices were seen and acknowledged. I recently read somewhere that it's fine to have different opinions 😉, so I'll just respond to some of the points you mentioned yourself.

After seeing your set-up I understand your point about not having the same worries about React/WebPack as I do. Still, I am curious how you feel about the claim that Matteo's approach of using stable, established technologies will lead to low maintenance (especially if the site will mostly end up static).

Related to that:

bc: I simply disagreed with building and maintaining a custom site generator when the tools for that already exist. I'll never have enough bandwidth to maintain the core of the project and a custom site generator.

This is a valid argument on its own, but OTOH, Matteo already did the "building" part of the site generator. If he is willing to handle (most) of the "maintenance" part too (which I argued won't be too high), that saves you from worrying about said bandwidth at all.

bc: I borrowed the idea for git book from things like enzyme API documentation which is entirely based on MD files. Seems like a reasonable approach 😕

To be clear, I was only trying to argue that Matteo's choices seemed reasonable and why - I have no stake in doing it his way, and no experience with gitbook (other than as an end-user of the resulting documentation). Maybe it is the most amazing way to write MarkDown-based documentation, and let others contribute to it!

[JobLeonard]

So I haven't been able to actively keep up with the development of Walt (as John Lennon used to say: "life is what happens while you are busy making other plans."), but I think I can start making some time in the weekends again to contribute, and I figure taking up the documentation role would be a low-treshold way to do so. Plus it would help me master Walt/ASM.

[ballercat]

Hey, that is great. Looking forward to all the questions & bug reports! The current documentation is light years behind the feature set.

[JobLeonard]

Can you give a TL;DR? ;)

[ballercat]

Sure, I think I have an existing issue I can update with new todos sometime this weekend.

[konsumer]

I'd be happy to help with the website and documentation.

I really like gatbsy, and it's easy to work with a bunch of markdown files and just use react as the template language. I have made a few gatsby starters, and made some plugins, and a bunch of sites with gatsby. I'd be happy to convert the awesome work @matteocargnelutti did + the code-playground. As for "over-engineering" I totally understand what @matteocargnelutti means, but with gatsby it's literally just "drop a markdown file with some frontmatter in this directory." Maybe I can just make a lil demo project real quick, and we can all evaluate it.

I have generated pretty nice API docs with jsdoc-to-markdown in the past, but documentationjs looks super-nice. I could generate markdown files, or even better generate the docs on the fly, in gatsby, directly from the source (via gatsby-transformer-documentationjs.)

I can get started with @matteocargnelutti's design, as some gatsby templates, and integrate the playground, and maybe confer with others about how we should do API docs, and any other markdown we should use.

Are there any other doc-site resources I should know about?

[konsumer]

I started work on it here, which is running here.

It still needs a lil work on the styling and stuff, but overall it should be pretty straightforward to update and modify. I think it could be much further simplified, which I will do when I have some time, if people are interested in this direction.

If you view the source on pages, you can see it's static. It is meant to work with javascript disabled (view source, and you can see the actual content) but I need to fix something about how it's dealing with the path-prefix (all referenced files are at / not /walt-docs.)

[ballercat]

Hi there.

I am very interested in this direction. Thank you for taking on this effort. There aren't' any additional resources other than the wiki. The wiki is a bit old now but there is some decent stuff there.

I checked out the site and it looks like a good start. I'm very interested in hearing more on using the source code to build out the API documentation (I think it was mentioned in one of the todos).

Nice work.

[konsumer]

I'm trying to incorporate the Explorer into the build, and just can't seem to get it to work. I got through various errors related to build (SSR doesn't have window or navigator, or most other browser globals) and it builds without error, but I can't make it run in this stack in dev server (npm start.)

I get this error:

/Users/konsumer/Desktop/walt-docs/src/components/explorer/index.js
    9:8   warning  'waltCompiler' is defined but never used   no-unused-vars
   13:20  warning  'closurePlugin' is defined but never used  no-unused-vars
   55:22  warning  eval can be harmful                        no-eval
  113:32  error    'getAST' is not defined                    no-undef
  155:13  warning  Expected a default case                    default-case

When I grep for it, in the example dir, the line that causes error is the only thing returned. where is this defined?

[ballercat]

It's a bug caused by a previous refactor to the compiler API, the explorer logic wasn't properly updated. I'm patching the getAST issue in #160

[konsumer]

Ah. My copy with all the guards for navigator and global instead of window are in that repo, should I make a PR for packages/walt-docs over here? It's not complete, it will just get people a little further if they are doing SSR.

[konsumer]

It might make sense to integrate the separate repo into this monorepo now, as it will also also allow me to start testing documentation. Should i just run it on walt-compiler or are there other things that should get API docs, too?

[ballercat]

Sounds good. We can start with the compiler as an MVP and use the learnings from that on another package as a follow-up.

[konsumer]

Ok everything moved into the PR (so that code will be in /docs. I'm going to delete my temp repo.

You can see the running version of it, here.