Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

"Write your own generator" docs #206

Closed
necolas opened this Issue · 36 comments

9 participants

@necolas

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 :)

@sononix

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
#171

@passy
Owner

@addyosmani is working on some great docs covering all that. :)

@passy passy was assigned
@sindresorhus

We now have an intro tutorial http://yeoman.io/generators.html

@necolas @sononix What more do you think we need to cover?

@necolas

It's a good start! Some feedback:

  1. 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.

  2. 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
    create generator/index.js
    create generator/templates/readme.md
    
  3. 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.

  4. 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.

  5. 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.

  6. 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).

  7. 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.

  8. 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.

@kevva
Collaborator

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.

@addyosmani
Owner

Thanks for the detailed feedback, @necolas! I appreciate you taking the time to read through the new docs.

  1. That's a very good point and one that I had glossed over when writing. We'll address this shortly.
  2. Bug - will fix.
  3. We should clarify for sure.
  4. Confirmed bug.
  5. I think that we should have a list of methods being used prior to the example and walk through what each of them is doing. Alternatively, we should better comment those examples.
  6. Good idea! I like it.
  7. I think the remote API would be worth covering, but we should make this more clear.
  8. When writing the docs I wanted to avoid making the getting started guide overly verbose, which I thought we would end up doing if too much of the magic was captured there rather than in the internal generator docs. We'll try to find a balance between those features that are worth documenting here and those which wouldn't be of great help to the average generator author.

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?

@kevva
Collaborator

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.

@necolas

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.

@stephenplusplus

@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!

@passy
Owner

@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. :)

@stephenplusplus

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 :alarm_clock:ed.

@stephenplusplus

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 stephenplusplus referenced this issue in yeoman/yeoman
Closed

Docs for 1.0 #829

8 of 14 tasks complete
@marcoslhc

@stephenplusplus that's a nice, gentle introduction to Generators. Thanks!

@stephenplusplus

Thank you! Is there anything you were left wondering that you think should be covered/given more attention?

@marcoslhc

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.

@addyosmani
Owner

@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.

@passy
Owner

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.

@addyosmani
Owner

Feedback:

  • "Ever used yo webapp to bootstrap your application" - let's link up to the getting started guide
  • "I'm all done. Running bower install & npm install for you to install the required dependencies. If this fails, try running the command yourself" - let's split this across two lines.
  • "If you hang around the Yeoman | Generator GitHub long enough" - let's change to Yeoman > Generator
  • "There's also the #yeoman freenode IRC room you can hop in" - let's link up to freenode webchat here
  • "As I'm typing this sentence, there are over 90 generators available on NPM-- generators for Angular, Backbone, Chrome apps, FireFox OS apps, Express stacks, PHP frameworks, and more" - let's link up to these generators.

We should probably also link up to the generator API docs etc (as per on the current doc).

@marcoslhc
  • The links to showdown and showup links back to the article. Should be https://github.com/coreyti/showdown and https://github.com/stephenplusplus/showup
  • The gists required are not there, just the Gruntfile.js (I'm assuming this is WIP and soon will be all uploaded)
  • re thinking about #206 (comment) this should have a paragraph and example on how to use Generator properties and user responses in the template files. Are the gist clear enough to cover this?
@stephenplusplus

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. :sunny: :boat: -> :car: :baby: :baby_bottle:

@addyosmani
Owner
@stephenplusplus

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:

  • Home

  • Why Yeoman?

  • Getting Started

    • Road to 1.0
    • Migrating from 0.9
    • Deployment
    • Roadmap
    • Support
    • Package Manager
    • About
  • Generator

    • How To (current walkthrough ["Setup" through "Writing Your Next Generator"])
    • Support & Reference Materials (current "Get Help" and "Reference Materials")
    • FAQ

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!

@addyosmani
Owner
@stephenplusplus

I took a stab at re-structuring the nav a bit...

  • added in a Generators section, with some sub-links
  • promoted "About" to the top of "Getting Started"
  • moved "Road to 1.0" and "Migrating from 0.9" under "Documentation", as I think these are less important to a Yeoman newcomer than the features of Yeoman itself, which should be highlighted

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!

@SBoudrias
Owner

@stephenplusplus Nice job, that really make sense to me!

@stephenplusplus

@SBoudrias Thanks! And, phew! :)

@marcoslhc

@stephenplusplus excellent work :100: , 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.

@stephenplusplus

@marcoslhc Thank you, I'm glad it helped. And that would be great! Sharing anything you learned with others is always a good idea :)

@stephenplusplus

Jekyll is quite easy and enjoyable! http://stephenplusplus.github.io/yeoman.io

@addyosmani
Owner

Love it. Let's land it :)

@stephenplusplus stephenplusplus referenced this issue in yeoman/yeoman.io
Merged

Update for the new Generator links! #63

@stephenplusplus

Woo! About to update the Yeoman wiki, then it'll be ready!

@addyosmani
Owner

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?)

@stephenplusplus

I switched the nav stuff over in this PR: yeoman/yeoman.io#63

@sindresorhus

Yay. Excellent work @stephenplusplus :cake:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.