Feature: Js and Css document generator

[delebash]

Might be a good feature to add.

I was thinking about using https://github.com/tj/dox, it just generates a json file based on jsdoc without generating an html app. Then we could make an aurelia app/template for displaying the data. It could be a simple display or a fancy app like YuiDoc, this way we can include a default template or the user can build there own based on the json file.

Also would like to include a css style guide generator but still looking into that.

What do you think?

[zewa666]

There's some work going on for the official Aurelia Docs, I'd really like to wait and see what the result over there is, might can be reused for this as well.

Regarding the css stuff is it something like this http://trulia.github.io/hologram/ you're talking about?

[delebash]

sounds good,

Yes I like hologram below are a few others generators just so you can take a look, I think github uses or used kss

Reference http://alistapart.com/blog/post/style-guide-generator-roundup

[zewa666]

So for the css stuff, what would you expect the generator to do exactly? Maybe you could provide a simple example of how you think the process should work

[delebash]

Sure if you look at either the kss example http://primercss.io/scaffolding/ or the hologram example http://trulia.github.io/hologram-example/base_css.html

It generates an html app that has all the components, buttons ect used in your project with the related css class

It makes it easier for a consumer to understand how your css is used, ie what class do I need to change to change the style for all primary buttons. Y can provide documentation in your css or sass describing what each main class is used for. This makes it easy for you to identify what class you need to change the background color on to change all main buttons. In addition the html generated style guide gives you a demo of what it currently looks like, so you can identify that element in your working app.

In aurelia's case when you create a new app every time you build it would create a doc folder with a generated css style guide. The guide would be configurable to include/exclude files/folders. I personally like the idea of just generating a data file in json like https://github.com/tj/dox does for javascript then have a default template to provide a view, that way if the user doesn't like the look and feel of the generated html they can just create their own view and bind it to the data.

I am still new to using style guides myself, but so far I like it, it really helps someone understand your app, instead of having to open the css file and wade through it. One thing about style guides is that you don't include everything in the styleguide comments, just the stuff that you want to expose to a consumer allowing them to skin your doc, think of it as documentation describing how create a custom skin for your app(sort of).

Does this make sense? If you need more info or more use case examples let me know.

Thanks, Dan

[zewa666]

Sounds good. But I think this might be the wrong place to do it. I think a gulp task in the official repo might be better suited for this. Can I ask you to open an issue with your last explanation in the Skelly Repo https://github.com/aurelia/skeleton-navigation ?

Haven't worked so far with css style guides but it sounds very interesting, I'm pretty sure our UX guy would also like to see something like this as an official guideline.

[delebash]

Done see https://github.com/aurelia/skeleton-navigation/issues/68