You can clone with
HTTPS or Subversion.
Need better docs around writing your own generator, common patterns, etc. It's currently not a great.
I will help upstream some of this based on my experience fumbling around writing a generator. Hopefully others can point out what I got wrong and help me learn more in the process :)
would agree issue que is fragmented on what the correct process is at the moment - without the ability of being able to write you own generator the point of yeoman seems somewhat diluted when you need to config in multiple places
can someone highlight a best practice - I would imagine installing globally though I can see advantages of just locally the problem here becomes where does your custom package.json file fit into the workflow or component file for that matter - the only way I see it is if you have you own global generator - chicken and the egg senario
some one mentions angular needs to be installed locally
@addyosmani is working on some great docs covering all that. :)
We now have an intro tutorial http://yeoman.io/generators.html
@necolas @sononix What more do you think we need to cover?
It's a good start! Some feedback:
Not sure about the instructions on creating a boilerplate generator saying you should clone the generator-boilerplate repo. If people are making their own generators, should they have all of that repo's history in it? Probably not.
This section is confusing because the code example is a different command.
Then to create a new generator call: yo generate:generatorName
$ yo generator generator
Then to create a new generator call: yo generate:generatorName
$ yo generator generator
Isn't this.install now this.bowerInstall? Or way of invoking both Bower and npm install? Both the methods are referenced in the context of Bower install.
Half way through the example for Bootstrap's generator, it switches from example using Generator to those with AppGenerator. It might be confusing for people.
The "scaffolding an index" section has no explanation of what's going on with appendScripts and appendFiles. If this example is too complicated to explain each method, maybe something simpler would be better.
The section on hookFor could be restructured so you don't show an example use of hookFor directly after talking about running sub-generators on their own. Maybe talk about sub generators, show the command, and then move on to talking about how to use them in the main generator of the module (inc. the hookFor example code).
The "remotely pull in files" part is confusing. Looks like a lingering reference to this.appPath, which I thought was some custom thing that Angular team added to their generator and involves adding that property to component.json. I don't know if you want to explain the remote API here. If not, maybe remove that example and just mention that it's possible and point to the API docs.
Still doesn't really explain the magic behind the scenes. Like, how it doesn't matter what my functions on the prototype are called, Yeoman's generator just runs them all. Or how properties of this can be referenced in your templates to dynamically generate files (e.g., based on app name, etc.).
An aside, while reading the README for generator-generator I was reminded that the massive Yeoman ASCII art appearing in the terminal all the time is annoying. Is there a plan to make it smaller or get rid of it?
Anyway, thanks for working on this! Hopefully I can give some more valuable feedback and suggestions once I have time to get back to the generator.
Thank you! I've fixed some of the things. Will go over the rest tomorrow. I agree that some of it can be quite hard to grasp since it's very code heavy without any deep explanations what the functions actually do. Should probably rewrite some of the code examples to be more generic too.
Thanks for the detailed feedback, @necolas! I appreciate you taking the time to read through the new docs.
In generator-generator, I believe the artwork was actually heralded as a feature :) @passy maybe we should remove it by default or provide a simpler option for getting rid of it if an author doesn't want to include it?
Instead of explaining all of the magic behind the scenes in this guide we should link to the API where appropriate. Else it will get overly verbose as you say.
Yeah, you could link to the API docs, but they also need to demystify some of the magic. Or at least make it clearer how the overall system works. Then it will be in a great place to get people up and running very quickly.
@addyosmani Here's an in-progress rough draft of some documentation I'm working on... https://github.com/stephenplusplus/yeoman/wiki/Generators
As it turns out, it might fit better as a blog post, but if you think it can be fit in to yeoman.io, I'm happy to see it there!
If you (or anyone else here) reads over it, let me know if you think I'm headed in the right direction, or where I should take it. Also, if you find any incorrect bits, please let me know!
@stephenplusplus I really enjoy your writing style. I was a bit sad when the article was over.
Two things: I think you should mention that the name of the directory is important here. You let the user create generator-blog, but it might make sense to add a sentence about the fact that this name is used to enable yo blog later on. Also, the handsome devil looks a bit more beaten up than he should in the rendered markdown. :)
Thank you, and good points! I just read it again and see that it needs some clean up. I'll be out of town this weekend, so if I disappear, don't be ed.
Another late-night pass at this... https://github.com/stephenplusplus/yeoman/wiki/Generators
I know I'll read it tomorrow and catch a bunch of stuff, but if anyone beats me to it, please let me know!
@stephenplusplus that's a nice, gentle introduction to Generators. Thanks!
Thank you! Is there anything you were left wondering that you think should be covered/given more attention?
I think you summarize the basics very well, and is a pretty complete guide to start writing generators. Anything else should be put somewhere else in the docs.
@stephenplusplus Thanks. I'll go through and do another more detailed review right now. I think the updates you've made are exactly what we needed.
I disagree that this would be better as a blog post - it would be more than ideal for the live docs site. One last thing I think we should do is double check the list from Nicolas to double-check there's nothing (for a starter guide) we're missing.
I agree with @addyosmani that this is a great fit for the docs site. Blog posts also have the of being posted at a certain date and updating them is rather painful.
We should probably also link up to the generator API docs etc (as per on the current doc).
Thanks everyone for the review and catching those things. I will make all of those changes later tonight. I'm about to head back home after a weekend-sized vacation. ->
Gists updated, links added, lines split!
Added a slightly modified FAQ back in, and a Reference Materials section, formerly known as Generator Internals.
I really like the Generator Snippets section as well, I just don't want the page to become counter-helpful by being intimidating. Is it possible to have Generator sub-pages, as in:
The more time I spend with the generator, the more I feel it deserves major attention; both to help the learning experience and to communicate the "oh my gosh, more people need to use this" point. There's so much information to relay on yeoman.io and GitHub, it's nearly impossible to find the perfect way to present everything in the most beneficial way possible. However, I wanted to at least bring it up to see if anyone had ideas for how to improve. I'll be sure to let you know if I come up with any!
I took a stab at re-structuring the nav a bit...
I'm new to this setup, though (Jekyll, Wiki tie-in, etc.), but is this kind of thing possible, or do you see any downsides or drawbacks?
As far as the walkthrough, it's ready for final review. I'm always happy to make changes! If we implemented the sub-section and new nav idea, I believe I'll need to split up the pieces of the Guide into different pages (FAQ, Writing Your First Generator, etc.)
And lastly, the idea you mentioned RE: personal workflow/screencast would be great! After we find some resolution to the above items, I'm glad to help out there!
Oh, and Generators would need an icon!
@stephenplusplus Nice job, that really make sense to me!
@SBoudrias Thanks! And, phew! :)
@stephenplusplus excellent work , is really helpful. Finishing touches to my own generator, hopefully i'll publish it by the end of the week with plenty of annotations and comments. I think that should help too.
@marcoslhc Thank you, I'm glad it helped. And that would be great! Sharing anything you learned with others is always a good idea :)
Jekyll is quite easy and enjoyable! http://stephenplusplus.github.io/yeoman.io
Love it. Let's land it :)
Woo! About to update the Yeoman wiki, then it'll be ready!
It's up! https://github.com/yeoman/yeoman/wiki/Generators
I just landed the submodule bump too so its live http://yeoman.io/generators.html :) Can we also get a PR together for the other changes (e.g TOC etc?)
I switched the nav stuff over in this PR: yeoman/yeoman.io#63
Yay. Excellent work @stephenplusplus