Cashmere Demo Page

[benjanderson]

The demo site was based off the site @andrew-frueh example of a style guide on spark. The current version loosely resembles that example. Our demo of our components needs improvement to bring it up to modern style guide standards

This is a list of things that need to be done, but is not comprehensive:

• [x] landing page (example: https://material.angular.io/
• [x] global navigation
• [x] link back to our github repo
• [x] global styles for documentation
• [ ] tabbed code (eg. html / typescipt) component
• [x] component list side bar styling
• [x] version number / alpha release warning

We desperately need help, if you wish to contribute please post your intention here or on #cashmere channel on slack. Please make pull requests small

[joeskeen]

Before jumping into tabbed code, I'd like to add code syntax highlighting. ngx-highlightjs looks promising, what do you think @benjanderson?

[corytak]

My .02 if it's just for the demo project, I think it would be fine to add a library as a devDependency. If it's going into a component that we're shipping we'll probably need to evaluate libraries more strictly.

[joeskeen]

As a n00b to the project, how are we separating out the demo project (cashmere.azurewebsites.net) from library code? IMHO the demo project should have its own package.json so we don't inadvertently add dependencies to the library.

[benjanderson]

I am ok with libraries in the demo project as long as they are not included in the main npm package. I am not sure how that works and will defer to @corytak if that is possible

[corytak]

The package.json file in the dist folder is generated in build.js

shell.cp(`-Rf`, [`package.json`, `LICENSE`, `README.md`], `${NPM_DIR}`);
shell.sed('-i', 'dependencies','peerDependencies','dist/package.json');

Basically, it's copying the package.json to the dist folder and replacing dependencies with peerDependencies. To be included in the npm package/library, the new module needs to be added to src/app/lib/cashmere.ts (the public api). The app.module.ts is the demo app and each component so far has a demo folder as part of its code.

I'm open to the idea of a separate package.json file for the demo app but am unsure about what it's implementation might look like or the best way to keep the two in sync.

[joeskeen]

In many open source projects, the documentation/demo/reference implementation site is separated from the library code in a separate sub-folder. (You can see this practice used with GitHub Pages.) I think this makes for a cleaner separation in the project, as you aren't ever left guessing what files are part of the package as opposed to the demo site.

If we did it this way, we could have the root of the repository be the packaging root, and either use .npmignore or files in package.json to exclude the documentation site, which would be in the /docs folder (the entire Angular CLI project). Now when you're just working on the website you know exactly which files you can touch. The next thing we'd want to do is reference the Cashmere library from the documentation site app. We can set it up so that the app loads the Cashmere Angular module(s) as a dependency and things should work as expected.

IMHO this would make it much easier for newcomers to the project to know how things work, without having to understand all of the magic in the build scripts generating a package.json file on the fly.

Thoughts?

[corytak]

@joeskeen I like the idea of removing any magic out of the process and making the package less intimidating for new contributors. +1 from me.

[joeskeen]

I think I'll make a separate issue for this effort, as the scope is beyond the demo page.

[andrew-frueh]

@benjanderson & @joeskeen - I'm planning on some work into this one when I have spare time this week. I'll take "global styles", "link back to repo", "component list styling", and "version number / alpha release warning". Let me know if either of you have already put work into any those that haven't been merged.