Skip to content
Browse files

Bringing our documentation in line with the version used for yeoman.io

  • Loading branch information...
1 parent 6a44125 commit 55af612654f8c7ace8a6ddb156c9f12f1eeebe02 @addyosmani addyosmani committed Sep 9, 2012
View
2 docs/cli/commands/build.md
@@ -1,6 +1,6 @@
-## build
+## <a href="#build" name="build">build</a>
Usage: `yeoman build`, `yeoman build:<target>`
View
5 docs/cli/commands/help.md
@@ -1,5 +1,5 @@
-## Help
+## <a href="#help" name="help">help</a>
* `yeoman --help` or `yeoman help`
@@ -19,5 +19,4 @@ yeoman search # Query the registry for matching package names
yeoman lookup # Look up info on a particular package
```
-Note that commands may also support additional flags and so we recommend consulting the documentation for specific
-commands for the complete details.
+Note that commands may also support additional flags and so we recommend consulting the documentation for specific commands for the complete details.
View
36 docs/cli/commands/init.md
@@ -1,25 +1,22 @@
-## init
+## <a href="#init" name="init">init</a>
Usage: `yeoman init`, `yeoman init generatorName`, `yeoman init generatorName:subgenerator`
-Helps you kick-start a new web application by asking a number of questions about what you would like to include.
-These answers are used to scaffold out a file structure for your project.
+Helps you kick-start a new web application by asking a number of questions about what you would like to include. These answers are used to scaffold out a file structure for your project.
-The init template is based on:
+The default `init` template is based on:
* HTML5 Boilerplate for the main base
* Compass Twitter Bootstrap for the SASS files as the CSS files are authored in SASS
* Twitter Bootstrap for the optional list of JavaScript plugins (optional)
* RequireJS for AMD module and script loading support (optional)
* RequrieHM for experimental EcmaScript 6 module syntax support on top of RequireJS (optional)
-By default we support Compass and CoffeeScript, so if your project includes any .coffee files, these will be
-compiled when either `server` or `build` tasks are being run.
+By default we support Compass and CoffeeScript, so if your project includes any .coffee files, these will be compiled when either `server` or `build` tasks are being run.
-If everything has been installed successfully, running `yeoman init` will present you with a welcome
-screen to kick off your project that looks a little like this:
+If everything has been installed successfully, running `yeoman init` will present you with a welcome screen to kick off your project that looks a little like this:
```shell
@@ -31,6 +28,7 @@ screen to kick off your project that looks a little like this:
o/ --- \
_\ /_
+Out of the box I include HTML5 Boilerplate, jQuery and Modernizr.
.. Invoke app ..
@@ -48,24 +46,19 @@ yeoman init angular #angularjs seed
yeoman init ember #ember app based on ember-rails
```
-Yeoman comes with a powerful system of Generators for scaffolding out applications using any number
-of boilerplates, frameworks and dependencies. Generators can be called in a project which has already
-been initialized with a basic Yeoman application structure OR may contain all of the files needed for the
-application structure themselves. By default, one can call a generator as follows:
+Yeoman comes with a powerful system of Generators for scaffolding out applications using any number of boilerplates, frameworks and dependencies. Generators can be called in a project which has already been initialized with a basic Yeoman application structure OR may contain all of the files needed for the application structure themselves. By default, one can call a generator as follows:
```shell
-yeoman init generatorName:subgenerator #e.g init angular:all
+yeoman init generatorName #e.g yeoman init angular
```
-In the case of a Generator named "angular", a grouping sub-generator called `all` may exist for scaffolding
-out all of the files needed for a new AngularJS application. One would use this as follows:
+In the case of a Generator named "angular", a grouping sub-generator called `all` may exist for scaffolding out all of the files needed for a new AngularJS application. One would use this as follows:
```shell
yeoman init angular:all
```
-The idea here is that the Generator would pull in AngularJS, its common dependencies and write out the
-boilerplate needed for a basic Controller and any other components the framework may require.
+The idea here is that the Generator would pull in AngularJS, its common dependencies and write out the boilerplate needed for a basic Controller and any other components the framework may require.
As we understand that it's unlikely a user will wish to manually type out the ":all" part of each generator, we support a catch-"all". If a generator has a sub-generator (grouper) called "all" we will attempt to call "all" when you try running the top-level generator. This allows a user to simply call:
@@ -74,8 +67,7 @@ yeoman init angular
```
and has it defer to `angular:all` automatically.
-If one then wishes to create further AngularJS controllers, one can simply call the 'controller' sub-generator as
-follows:
+If one then wishes to create further AngularJS controllers, one can simply call the 'controller' sub-generator as follows:
```shell
yeoman init angularjs:controller controllerName
@@ -89,9 +81,7 @@ Similarly, a Backbone.js Generator may be used as follows:
yeoman init backbone
```
-where the above would result in boilerplate for models, views, collections and a router being written to
-the current application directory, as well as Backbone.js and its dependencies being pulled in. One could
-then call the different sub-generators for the Generator as follows:
+where the above would result in boilerplate for models, views, collections and a router being written to the current application directory, as well as Backbone.js and its dependencies being pulled in. One could then call the different sub-generators for the Generator as follows:
```shell
yeoman init backbone:model modelName
@@ -106,7 +96,7 @@ To list out all of the generators currently available locally, you can use the `
yeoman init --help
```
-This will print out a list of existing generators as follows:
+This will print out a list of existing generators, including some of the below:
```shell
Please choose a generator below.
View
19 docs/cli/commands/install.md
@@ -1,12 +1,12 @@
-## install
+## <a href="#install" name="install">install</a>
Usage: `yeoman install <packageName>`, `yeoman install <package1> <package2>`
-Installs a package <name> and any packages that this depends on using Twitter Bower. A package is a folder containing a resource described by a package.json file or a gzipped tarball containing this information.
+Installs a package and any packages that this depends on using Twitter Bower. A package is a folder containing a resource described by a package.json file or a gzipped tarball containing this information.
-Running yeoman install <name> will install the dependencies in your projects browser_modules folder.
+Running yeoman install packageName will install the dependencies in your projects browser_modules folder.
Example:
@@ -34,16 +34,3 @@ bower install http://code.jquery.com/jquery-1.7.2.js
bower install ./repos/jquery
```
-## Available Packages
-
-Currently available packages:
-
-* **backbone** *git://github.com/paulirish/package-backbone.git*
-* **jquery-ui** *git://github.com/maccman/package-jquery-ui.git*
-* **jquery** *git://github.com/maccman/package-jquery.git*
-* **knockout** *git://github.com/SteveSanderson/knockout.git*
-* **modernizr** *git://github.com/josh/package-modernizr.git*
-* **spine** *git://github.com/maccman/spine.git*
-* **underscore** *git://github.com/paulirish/package-underscore.git*
-
-For further information, see the section on the package manager.
View
2 docs/cli/commands/list.md
@@ -1,6 +1,6 @@
-## list
+## <a href="#list" name="list">list</a>
Usage: `yeoman list`
View
5 docs/cli/commands/lookup.md
@@ -1,11 +1,10 @@
-## lookup
+## <a href="#lookup" name="lookup">lookup</a>
Usage: `yeoman lookup <packageName>`
-Performs a lookup in the Bower registry for a package of a specific name. One would use this to confirm
-that a package exists under a specific name (e.g `jquery`), othewise `search` should be used for broader queries.
+Performs a lookup in the Bower registry for a package of a specific name. One would use this to confirm that a package exists under a specific name (e.g `jquery`), othewise `search` should be used for broader queries.
Example:
View
2 docs/cli/commands/search.md
@@ -1,6 +1,6 @@
-## search
+## <a href="#search" name="search">search</a>
Usage: `yeoman search <keyword>`
View
9 docs/cli/commands/server.md
@@ -1,11 +1,10 @@
-## server
+## <a href="#server" name="server">server</a>
Usage: `yeoman server`
-Launches a preview server on port 3051 that allows you to access a running version of your application
-locally.
+Launches a preview server on port 3051 that allows you to access a running version of your application locally.
It also automatically fires up the `yeoman watch` process, so changes to any of the applications
files cause the browser to refresh via [LiveReload](http://livereload.com). Should you not have
@@ -15,9 +14,7 @@ Any changes to CoffeeScript or Compass files result in them being recompiled, me
no manual intervention is required to write and preview code in the format you feel most
comfortable with.
-`yeoman server` generates an intermediate build directory in your project root which (called `temp`)
-contains the compiled files mentioned above as well as the basic blocks needed to preview your application.
-A complete build can be generated using `yeoman build`.
+`yeoman server` generates an intermediate build directory in your project root which (called `temp`) contains the compiled files mentioned above as well as the basic blocks needed to preview your application. A complete build can be generated using `yeoman build`.
To quit the server, simply run `yeoman quit server` and this will kill the Python server
process.
View
2 docs/cli/commands/test.md
@@ -1,6 +1,6 @@
-## test
+## <a href="#test" name="test">test</a>
Usage: `yeoman test`
View
11 docs/cli/commands/uninstall.md
@@ -1,9 +1,9 @@
-## uninstall
+## <a href="#uninstall" name="uninstall">uninstall</a>
-Usage: yeoman uninstall <packageName>
+Usage: yeoman uninstall packageName
-Removes the package <packageName> from the current project.
+Removes the package `packageName` from the current project.
Example:
@@ -12,7 +12,7 @@ yeoman uninstall backbone
# outputs:
-bower uninstalling /project/browser_modules/backbone
+bower uninstalling /project/components/backbone
```
Note: If you attempt to uninstall a package that is a dependency of other packages, yeoman (via Bower)
@@ -27,5 +27,4 @@ yeoman uninstall jquery
warning backbone depends on jquery
```
-This simply means that you should uninstall backbone (the top-level package with the dependency) if you
-wish to remove all traces of the jquery package.
+This simply means that you should uninstall backbone (the top-level package with the dependency) if you wish to remove all traces of the jquery package.
View
7 docs/cli/commands/update.md
@@ -1,10 +1,10 @@
-## update
+## <a href="#update" name="update">update</a>
Usage: `yeoman update <packageName>`
-Updates an already installed package <packageName> to the latest version available in the Bower registry.
+Updates an already installed package `packageName` to the latest version available in the Bower registry.
Example:
@@ -15,5 +15,4 @@ yeoman update jquery
bower checking out jquery#v1.7.2
```
-The `update` command will also update any other packages in your project relying on this dependency to use
-this most recent version if any update is applied.
+The `update` command will also update any other packages in your project relying on this dependency to use this most recent version if any update is applied.
View
195 docs/cli/generators.md
@@ -1,22 +1,21 @@
-## Generators
+## <a href="#generators" name="generators">generators</a>
-Generator templates allow you to scaffold out a project using a custom setup of boilerplates, frameworks and dependencies. The basic application generated when calling `yeoman init` actually uses a generator itself and they can be quite powerful.
+Generator templates allow you to scaffold out a project using a custom setup of boilerplates, frameworks and dependencies. The basic application generated when calling `yeoman init` actually uses a generator itself and they can be quite powerful.
+
+Some of the generators Yeoman includes out of the box include implementations for Backbone.js, Ember.js and Angular.js. These allow you to not only use complete boilerplates for an application but also scaffold out smaller parts such as Models, Views, Controllers and so on.
-### Getting Started
-Note: The guide listed below relies on commands which we are currently still being reintegrated. Specifically, the `generate` command needs to be reinstated to work with our `init` rewrite.
+### Getting Started
-yeoman init generate
+yeoman init generator
----------------------
The `yeoman init` command uses templates and prompts to create the files needed for a project.
-Running `yeoman init generate` by itself gives a list of available generators:
+Running `yeoman init --help` by itself gives a list of available generators:
-You can also use the alias `g` to invoke the generator command: `yeoman init g`
-
- $ yeoman init generate
- Usage: yeoman init generate GENERATOR [args] [options]
+ $ yeoman init generator
+ Usage: yeoman init generator GENERATOR [args] [options]
...
...
@@ -30,17 +29,18 @@ You can also use the alias `g` to invoke the generator command: `yeoman init g`
...
**Note**: You can install more generators through npm package and you can even create your own.
+Yeoman's own generators are available in a dedicated [repository](https://github.com/yeoman/generators).
Using generators will save you a large amount of time by writing boilerplate code, code that is necessary for the app to work.
Let's make our own controller with the controller generator. But what command should we use? Let's ask the generator:
-**Note**: All generators available have help text. You can try adding --help or
+**Note**: Generators available may have help text. You can try adding --help or
-h to the end, for example `yeoman generate controller --help`
.. Invoke controller ..
Usage:
- yeoman init generate controller NAME one two three [options]
+ yeoman init generator controller NAME one two three [options]
Options:
-h, --help # Print generator's options and usage
@@ -52,17 +52,14 @@ The controller generator is expecting parameters in the form of `generate contro
Let's make a `Greeting` controller with an action of `hello`.
- $ yeoman init generate controller Greeting hello
+ $ yeoman init generator controller Greeting hello
-What all did this generate? If made sure a bunch of directories where in our application, and created a controller file, a view file and / or template file
-and a test file.
+What did this generate? It made sure a bunch of directories where in our application, and created a controller file, a view file and / or template file and a test file.
Yeoman comes with a generator for data models too.
$ yeoman init generator model
-> TODO help output
-
Creating and Customizing Yeoman Generators & Templates
------------------------------------------------------
@@ -81,15 +78,15 @@ Creating and Customizing Yeoman Generators & Templates
When you create an application using the `yeoman init` command, you are in fact
using a Yeoman generator. After that, you can get a list of all available
-generators by just invoking `yeoman init generate`:
+generators by just invoking `yeoman init --help`:
$ yeoman init
$ cd app
- $ yeoman init generate
+ $ yeoman init --help
You will get a list of all generators that come with yeoman. If you need a detailed description for a given generator, you can simply do:
- $ yeoman init generate [generator] --help
+ $ yeoman init generator [generator] --help
### Creating Your First Generator
@@ -113,13 +110,12 @@ the following content:
this.write('app/js/initializer.js', "// Add initialization content here\n");
};
-`write` is a method provided by `yeoman.generators.Base`, and is a basic facade to the `grunt.file` API. When we "write" things, this happen relative to the
-working directory (that is the Gruntfile location, the Gruntfile is resolved internally, walking up the FS until one is found. This is most likely the root
+`write` is a method provided by `yeoman.generators.Base`, and is a basic facade to the `grunt.file` API. When we "write" things, this happen relative to the working directory (that is the Gruntfile location, the Gruntfile is resolved internally, walking up the FS until one is found. This is most likely the root
of the yeoman application).
-Our new generator is quite simple: it inherits from `yeoman.generators.Base` and has one method definition. Each "public" method in the generator is
-executed when a generator is invoked (first level method in the prototype chain, eg. `Base` class method are not called). There are two exceptions,
-generators won't run:
+Our new generator is quite simple: it inherits from `yeoman.generators.Base` and has one method definition. Each "public" method in the generator is executed when a generator is invoked (first level method in the prototype chain, eg. `Base` class method are not called).
+
+There are two exceptions, generators won't run:
- any method begining with the `_` prefix.
- a `constructor` method, specifically used with generators written in
@@ -133,7 +129,7 @@ Finally, we invoke the `write` method that will create a file at the given desti
Now, we can see that the initializer generator available to use if we output
the list of available generators in this application:
- $ yeoman init generate
+ $ yeoman init generator
Usage: yeoman generate GENERATOR [args] [options]
...
@@ -156,9 +152,7 @@ Before we go on, let’s see our brand new generator description:
Description:
Create files for initializer generator.
-Yeoman is usually able to generate good descriptions, but not in this particular
-case. We can solve this problem in two ways. The first one is calling desc
-inside our generator:
+Yeoman is usually able to generate good descriptions, but not in this particular case. We can solve this problem in two ways. The first one is calling desc inside our generator:
var util = require('util'),
yeoman = require('../../../');
@@ -183,7 +177,7 @@ Now we can see the new description by invoking --help on the new generator. The
Generators themselves have a generator:
- $ yeoman init generate generator initializer
+ $ yeoman init generator generator initializer
create lib/generators/initializer
create lib/generators/initializer/index.js
create lib/generators/initializer/USAGE
@@ -204,10 +198,7 @@ This is the generator just created:
util.inherits(Generator, yeoman.generatos.NamedBase);
-First, notice that we are inheriting from `yeoman.Generators.NamedBase` instead
-of `yeoman.Generators.Base`. This means that our generator expects at least one
-argument, which will be the name of the initializer, and will be available in
-our code in the variable `name`.
+First, notice that we are inheriting from `yeoman.Generators.NamedBase` instead of `yeoman.Generators.Base`. This means that our generator expects at least one argument, which will be the name of the initializer, and will be available in our code in the variable `name`.
We can see that by invoking the description of this new generator:
@@ -216,16 +207,11 @@ We can see that by invoking the description of this new generator:
Usage:
yeoman init initializer NAME [options]
-**Note**: The banner is not automatically generated yet for generators (the Usage: thing above). Same for options and arguments defined by the generator,
-they should show up during the help output. Right now, the USAGE file is dumped
-to the console as is.
+**Note**: The banner is not automatically generated yet for generators (the Usage: thing above). Same for options and arguments defined by the generator, they should show up during the help output. Right now, the USAGE file is dumped to the console as is.
We can also see that our new generator has an instance method called `sourceRoot`.
-This method points to where our generator templates will be placed, if any, and
-by default it points to the created directory
-`lib/generators/initializer/templates` (so the `sourceRoot(__dirname,
-'templates')` can be removed, this is the default).
+This method points to where our generator templates will be placed, if any, and by default it points to the created directory `lib/generators/initializer/templates` (so the `sourceRoot(__dirname, 'templates')` can be removed, this is the default).
In order to understand what a generator template means, let’s create the file
lib/generators/initializer/templates/initializer.js with the following content:
@@ -308,14 +294,9 @@ can be configured in your application Gruntfile, these are some defaults:
Looking at this output, it’s easy to understand how generators work in yeoman.
-Generator relies on hook and other generators, some don't actually generate
-anything, they just invokes others to do the work.
+Generator relies on hook and other generators, some don't actually generate anything, they just invokes others to do the work.
-This allows us to add/replace/remove any of those invocations. For instance,
-the `controller` generator invokes the `view` and `test-framework` hooks. These
-hooks tries to resolve their value from cli options first, then look at the
-Gruntfile for a generator property with the corresponding hook name, and
-finally defaults to the hook name if none were found.
+This allows us to add/replace/remove any of those invocations. For instance, the `controller` generator invokes the `view` and `test-framework` hooks. These hooks tries to resolve their value from cli options first, then look at the Gruntfile for a generator property with the corresponding hook name, and finally defaults to the hook name if none were found.
Since each generator has a single responsibility, they are easy to reuse,
avoiding code duplication.
@@ -325,21 +306,11 @@ the hooks. etc.
### Customizing Your Workflow by Changing Generators Templates
-In the step above we simply wanted to add a line to the generated helper,
-without adding any extra functionality. There is a simpler way to do that, and
-it’s by replacing the templates of already existing generators, in that case
-`yeoman.generators.HelperGenerator`.
+In the step above we simply wanted to add a line to the generated helper, without adding any extra functionality. There is a simpler way to do that, and it’s by replacing the templates of already existing generators, in that case `yeoman.generators.HelperGenerator`.
-Generators don’t just look in the source root for templates, they also search
-for templates in other paths. And one of them is lib/templates. Since we want
-to customize `yeoman.generators.HelperGenerator`, we can do that by simply
-making a template copy inside lib/templates/yeoman/helper with the name
-helper.js.
+Generators don’t just look in the source root for templates, they also search for templates in other paths. And one of them is lib/templates. Since we want to customize `yeoman.generators.HelperGenerator`, we can do that by simply making a template copy inside lib/templates/yeoman/helper with the name helper.js.
-If you generate another resource, you can see that we get exactly the same
-result! This is useful if you want to customize your scaffold templates and/or
-layout by just creating edit.html.erb, index.html.erb and so on inside
-lib/templates/erb/scaffold.
+If you generate another resource, you can see that we get exactly the same result! This is useful if you want to customize your scaffold templates and/or layout by just creating edit.html.erb, index.html.erb and so on inside lib/templates/erb/scaffold.
### More On Generators
@@ -365,8 +336,7 @@ Generator.prototype.createSomething = function() {
// ... other methods ...
```
-Generators can also be written in CofeeScript, they just needs to be named with
-a `.coffee` extension (typically `lib/generators/generatorName/index.coffee`)
+Generators can also be written in CofeeScript, they just needs to be named with a `.coffee` extension (typically `lib/generators/generatorName/index.coffee`)
```coffee
yeoman = require 'yeoman'
@@ -391,42 +361,32 @@ They're usually layout like so:
├── index.js
└── templates
-Generators extends either `yeoman.generators.Base` or
-`yeoman.generators.NamedBase`. `NamedBase` is suitable to use for genetors that
-expects a "name" argument, such as `yeoman init model [NAME]`.
+Generators extends either `yeoman.generators.Base` or `yeoman.generators.NamedBase`. `NamedBase` is suitable to use for genetors that expects a "name" argument, such as `yeoman init model [NAME]`.
-Every public method in a generator are executed serially. Every first level
-method in the prototype chain, eg. inherited method in `Base` are not.
+Every public method in a generator are executed serially. Every first level method in the prototype chain, eg. inherited method in `Base` are not.
Two exceptions:
- any method beginning with `_` is not runned, you may use them as method
helper. They won't be called automatically on generator invokation.
- a `constructor` method, most likely when using CoffeeScript to implement the generator
-Either `Name` or `BasedName` are EventEmitters, you may use the EventEmitter
-API if you wish to (emit / on / once / ...)
+Either `Name` or `BasedName` are EventEmitters, you may use the EventEmitter API if you wish to (emit / on / once / ...)
grunt.file
----------
-Generators get mixed into their prototype the
-[grunt.file](https://github.com/cowboy/grunt/blob/master/docs/api_file.md#the-file-api)
-API. You can use read, readJSON, write, copy, mkdir, expandFiles, etc.
+Generators get mixed into their prototype the [grunt.file](https://github.com/cowboy/grunt/blob/master/docs/api_file.md#the-file-api) API. You can use read, readJSON, write, copy, mkdir, expandFiles, etc.
-Note that some of them have special additional logic attached, for `copy`,
-`read` and `write`.
+Note that some of them have special additional logic attached, for `copy`, `read` and `write`.
-`copy` and `read` make sure to prefix the source filename to be within the
-generator's source root (usually a `templates/` folder next to the generator
-implementation).
+`copy` and `read` make sure to prefix the source filename to be within the generator's source root (usually a `templates/` folder next to the generator implementation).
grunt.log
---------
In addition to the grunt.file API directly available into your generators, you
-can use the
-[grunt.log](https://github.com/cowboy/grunt/blob/master/docs/api_log.md#the-log-api) API as `this.log`
+can use the [grunt.log](https://github.com/cowboy/grunt/blob/master/docs/api_log.md#the-log-api) API as `this.log`
```js
@@ -439,19 +399,11 @@ Generator.prototype.doingSomething = function() {
sync vs async
-------------
-Methods are expected to run synchronously by default. This is fine for most
-cases, and will be just what you need for most common operations. Every file
-system method (copy, write, read, etc.) available are borrowed to grunt's,
-where most of them are implemented synchronously for conveniency.
+Methods are expected to run synchronously by default. This is fine for most cases, and will be just what you need for most common operations. Every file system method (copy, write, read, etc.) available are borrowed to grunt's, where most of them are implemented synchronously for conveniency.
-If you wish to run your method in an asynchronous way, you should tell the
-system to do so. Very similarly to how you would handle async stuff in grunt
-tasks.
+If you wish to run your method in an asynchronous way, you should tell the system to do so. Very similarly to how you would handle async stuff in grunt tasks.
-If a method is asynchronous, `this.async` must be invoked to tell the system to
-wait. It returns a handle to a "done" function that should be called when the
-method has completed. Every non-falsy value (most likely an Error object) can
-be passed to the done function as a first argument to indicate a failure.
+If a method is asynchronous, `this.async` must be invoked to tell the system to wait. It returns a handle to a "done" function that should be called when the method has completed. Every non-falsy value (most likely an Error object) can be passed to the done function as a first argument to indicate a failure.
It this method isn't invoked, the method executes synchronously.
@@ -461,8 +413,7 @@ Generator methods
The following are methods available for generators.
NOTE: Methods provided by Grunt are not covered this guide and can be found in
-"Grunt's
-documentation":https://github.com/cowboy/grunt/blob/master/docs/api_file.md#the-file-api
+"Grunt's documentation":https://github.com/cowboy/grunt/blob/master/docs/api_file.md#the-file-api
**TBD**
@@ -478,18 +429,15 @@ A hash object holding all cli parsed options by nopt.
Adds an argument to the class and creates an instance property for it.
-Arguments are different from options in several aspects. The first one
-is how they are parsed from the command line, arguments are retrieved
-from position:
+Arguments are different from options in several aspects. The first one is how they are parsed from the command line, arguments are retrieved from position:
yeoman init NAME
Instead of:
yeoman init --name NAME
-Besides, arguments are used inside your code as a property (this.argument),
-while options are all kept in a hash (this.options).
+Besides, arguments are used inside your code as a property (this.argument), while options are all kept in a hash (this.options).
Options:
@@ -510,16 +458,15 @@ parsed by nopt as a this.options Hash object.
- name - The name of the argument
- options - Hash of configuration values where:
- - desc - Description for the argument.
- - type - Type for this argument, either Boolean, String or Number.
- - defaults - Default value for this argument.
- - banner - String to show on usage notes.
- - hide - If you want to hide this option from the help.
+- desc - Description for the argument.
+- type - Type for this argument, either Boolean, String or Number.
+- defaults - Default value for this argument.
+- banner - String to show on usage notes.
+- hide - If you want to hide this option from the help.
### generator.sourceRoot([path])
-Stores and return the source root for this class. This is used with `copy()`,
-`template()`, `read()`, etc. to prefix the relative path.
+Stores and return the source root for this class. This is used with `copy()`, `template()`, `read()`, etc. to prefix the relative path.
By default, takes the value of `templates/` next to the generator file.
@@ -534,9 +481,7 @@ cd into it.
Must be called within the constructor only.
-Register a hook to invoke a generator based on the value supplied by the user
-to the given option named "name". An option is created when this method is
-invoked and you can set a hash to customize it.
+Register a hook to invoke a generator based on the value supplied by the user to the given option named "name". An option is created when this method is invoked and you can set a hash to customize it.
```js
function MyGenerator(args, options, config) {
@@ -546,9 +491,7 @@ function MyGenerator(args, options, config) {
}
```
-Hooks work in a way that you can delegate the groundwork of scaffolding to
-other generators. They're totally inspired by Rails 3 generators [`hook_for`
-method](http://apidock.com/rails/Rails/Generators/Base/hook_for/class).
+Hooks work in a way that you can delegate the groundwork of scaffolding to other generators. They're totally inspired by Rails 3 generators [`hook_for` method](http://apidock.com/rails/Rails/Generators/Base/hook_for/class).
The example above will create a js framework option and will invoke a
generator based on the user supplied value.
@@ -571,22 +514,18 @@ generators: {
// ... more grunt config ...
```
-This is what allows any js framework to hook into Yeoman as long as it provides
-any of the hooks above.
+This is what allows any js framework to hook into Yeoman as long as it provides any of the hooks above.
#### Options
-The first and last part used to find the generator to be invoked are guessed
-based on constructor's `hookFor` invokes, as noticed in the example above. This
-can be customized with the following options:
+The first and last part used to find the generator to be invoked are guessed based on constructor's `hookFor` invokes, as noticed in the example above. This can be customized with the following options:
- `as` - the context to lookup, defaults to generator's name.
- `args` - arguments to pass through, defaults generator's arguments.
- `options` - options to pass through, defaults to generator's options.
- `config` - Grunt config to pass through, defaults to generator's config.
-Let’s suppose you are creating a generator that needs to invoke the controller
-generator from a unit test. Your first attempt is:
+Let’s suppose you are creating a generator that needs to invoke the controller generator from a unit test. Your first attempt is:
```js
// in lib/generators/awesome/index.js generator's constructor.
@@ -614,10 +553,7 @@ And now it will lookup at:
> Copy a source file to a destination path, creating intermediate directories if necessary.
-Grunt's
-[`grunt.file.copy`](https://github.com/cowboy/grunt/blob/master/docs/api_file.md#grunt-file-copy)
-is used, we simply make sure that relative path are prefixed by the generator's
-sourceRoot value.
+Grunt's[`grunt.file.copy`](https://github.com/cowboy/grunt/blob/master/docs/api_file.md#grunt-file-copy) is used, we simply make sure that relative path are prefixed by the generator's `sourceRoot` value.
```js
// similar to
@@ -647,29 +583,22 @@ grunt.option('verbose', false);
### generator.template(source, [destination], [data])
-Gets an underscore template at the relative source, executes it and makes a
-copy at the relative destination. If the destination is not given it's assumed
-to be equal to the source relative to destination.
+Gets an underscore template at the relative source, executes it and makes a copy at the relative destination. If the destination is not given it's assumed to be equal to the source relative to destination.
```js
this.template('Gruntfile.js');
```
-will copy and process the `templates/Gruntfile.js` file through
-`grunt.template.process`, and write the results to `./Gruntfile.js` relative
-the the application root.
+will copy and process the `templates/Gruntfile.js` file through `grunt.template.process`, and write the results to `./Gruntfile.js` relative the the application root.
-Another example is using a `templates/model.js` template to write at the
-`app/js/models/{name}-model.js` location in a `NamedBase` generator.
+Another example is using a `templates/model.js` template to write at the `app/js/models/{name}-model.js` location in a `NamedBase` generator.
```js
this.template('model.js', path.join('app/js/models', this.name + '-model.js'));
```
### generator.directory(source, [destination])
-Copies recursively the files from source directory to destination root
-directory. If the destination is not given it's assumed
-to be equal to the source relative to destination.
+Copies recursively the files from source directory to destination root directory. If the destination is not given it's assumed to be equal to the source relative to destination.
Each file is copied and processed through `grunt.template.process`.
View
3 docs/cli/modules.md
@@ -1,4 +1,5 @@
-## EcmaScript 6 Modules And Module Support
+
+## <a href="#modules" name="modules">EcmaScript 6 Modules And Module Support</a>
Note: This content is subject to change and may be removed prior to launch.
View
66 docs/cli/package_manager.md
@@ -16,12 +16,12 @@ In Bower, dependencies are listed in a ‘component.json’ file, similar to Nod
}
```
-Dependencies are then installed locally via the `yeoman install’ command. First they're resolved to find conflicts, then downloaded and unpacked in a local sub dir (browser_modules) to component.json, for example:
+Dependencies are then installed locally via the `yeoman install’ command. First they're resolved to find conflicts, then downloaded and unpacked in a local sub dir called components:
```shell
-/package.json
-/browser_modules/modernizr/index.js
-/browser_modules/modernizr/component.json
+/component.json
+/components/modernizr/index.js
+/components/modernizr/modernizr.js
```
This approach has a number of benefits.
@@ -35,41 +35,71 @@ This approach has a number of benefits.
The easiest approach is to use a Bower package statically is to then just reference the package manually from a script tag:
```shell
-&lt;script src="components/jquery/index.js"&gt;&lt;/script&gt;
+&lt;script src="components/modernizr/modernizr.js"&gt;&lt;/script&gt;
```
Similar to NPM, our Bower integration also allows users to easily search for and update packages easily. e.g
To search for a package:
```shell
-bower search jquery
+yeoman search jquery
```
-To update a package, you need to reference it by name:
+To install a package:
```shell
-bower update jquery
+yeoman install jquery
```
-To list installed packages:
+To update a package, you need to reference it by name:
```shell
-bower list
+yeoman update jquery
```
-To search for packages:
+To list installed packages:
```shell
-bower search packageName
+yeoman list
```
and so on.
-For more information on how to use Yeoman's Bower integration, please see our relevant command docs below:
+For more information on how to use Yeoman's Bower integration, please see our relevant command-line docs.
+
+
+##What distinguishes Bower from Jam, Volo or Ender? What does it do better?
+
+It's easiest to think of Bower as a lower level component then Jam, Volo, or Ender.
+
+All Bower really does is install git paths, resolves dependencies from a component.json, checks versions, and then provides api which tells you what it did.
+
+The major diversion from past attempts at package management in the front-end, is that Bower is working under the assumption that there is a single, common problem in frontend application development which needs to be solved: resolving dependencies and managing components. Unfortunately, most other attempts tried to tackle this problem in such a way that it ends up alienating communities which develop using different transports (sprockets, commonjs, requirejs, regular script tags).
+
+For example, someone developing with sprockets, can't use volo packages, can't use jam packages, and so forth.
+
+Bower is trying to solve the common problem, in an unopinionated way, and leave the opinions your build stack.
+
+What's more, things like Ender can and will consume bower as a dependency for simple git installation and use the package api to build a commonjs style require api include for the browser.
+
+Jam or Volo could do the same thing for amd if they were interested.
+
+##Volo is an arguably more established project and works with the GitHub search API. Will it take long for Bower to contain a decent number of packages?
+
+Of all the projects, Ender is objectively the most popular - with nearly 1000 more watchers than volo – and is used at major companies like twitter, disqus, etc.
+
+Bower by definition has every single package that volo does (git packages) and more - it actually works on internal networks and other git repositories not hosted on github.
+
+##We recently saw what happened when the NPM registry completely went down. Is a central point of failure possible for Bower and if so, do you have redundancy planned?
+
+There's no redundancy planned at the moment, as Bower just installs git urls. It's up to the url provider to establish redundancy.
+
+##Isn't having a package.json file going to conflict with my npm's package.json? Will this be a problem?
+
+Don't use a package.json – user component.json.
+
+##Bower is an open-source Twitter project. How well can we expect it to be maintained in the future?
+
+Twitter has a pretty good track record with there open source projects thus far, and has an entire engineer pool to work on it. Another good thing we can say is that Twitter.com is moving it's frontend architecture onto Bower, so it's fairly safe to say it will be maintained.
-* [install](https://github.com/yeoman/yeoman/blob/master/docs/cli/install.md)
-* [update](https://github.com/yeoman/yeoman/blob/master/docs/cli/update.md)
-* [search](https://github.com/yeoman/yeoman/blob/master/docs/cli/search.md)
-* [list](https://github.com/yeoman/yeoman/blob/master/docs/cli/list.md)
-* [lookup](https://github.com/yeoman/yeoman/blob/master/docs/cli/lookup.md)
View
52 docs/faq.md
@@ -1,22 +1,11 @@
# FREQUENTLY ASKED QUESTIONS
-### What is Yeoman?
-Yeoman is a robust and opinionated client-side stack, comprised of tools and frameworks that can help developers quickly build beautiful web applications. The project was initially announced at Google I/O and it's capabilities include:
-
-* Lightning-fast scaffolding — Easily scaffold new projects with customizable templates (e.g HTML5 Boilerplate, Twitter Bootstrap), AMD (via RequireJS) and more.
-* Automatically compile CoffeeScript & Compass — Our LiveReload watch process automatically compiles source files and refreshes your browser whenever a change is made so you don't have to.
-* Automatically lint your scripts — All your scripts are automatically run against jshint to ensure they're following language best-practices.
-* Built-in preview server — No more having to fire up your own HTTP Server. My built-in one can be fired with just one command.
-* Awesome Image Optimization — I optimize all your images using OptiPNG and JPEGTran so your users can spend less time downloading assets and more time using your app.
-* AppCache manifest generation — I generate your application cache manifests for you. Just build a project and boom. You'll get it for free.
-* Killer build process — Not only do you get minification and concatenation; I also optimize all your image files, HTML, compile your CoffeeScript and Compass files, generate you an application cache manifest and, if you're using AMD, we'll pass those modules through r.js so you don't have to.
-* Integrated package management — Need a dependency? It's just a keystroke away. I allow you to easily search for new packages via the command-line (e.g., yeoman search jquery), install them and keep them updated without needing to open your browser.
-* Support for ES6 module syntax — Experiment with writing modules using the latest ECMAScript 6 module syntax. This is an experimental feature that transpiles back to ES5 so you can use the code in all modern browsers.
-* PhantomJS Unit Testing — Easily run your unit tests in headless WebKit via PhantomJS. When you create a new application, I also include some test scaffolding for your app.
+### What are the goals of the project?
-Yeoman harnesses the power of a number of different open-source tools and libraries, including Grunt and Twitter Bootstrap.
+The short-term goals for Yeoman are to provide developers with an improved tooling workflow so that they can spend less time on process and more time focusing on building beautiful web applications. Initially, we hope to make it as easy as possible to work with existing frameworks and tools developers are used to using.
+Long-term, the project may also assist developers with creating applications using modern technologies such as Web Components.
### What is a command-line interface?
@@ -28,30 +17,49 @@ A command-line interface is a means for developers to interact with a system usi
A package manager runs through a command-line interface and is a tool for automating the process of installing, upgrading, configuring and managing dependencies for projects. An example of a package management registry is NPM.
-### What are the goals of the project?
+### How does Yeoman differ from Grunt?
+
+Yeoman builds upon a number of open-source tools to offer an opinionated workflow that helps developers achieve common tasks more easily.[Grunt.js](http://gruntjs.com) is one of these tools and powers our underlying build process and task plugin architecture.
+
+On top of this architecture, we've highly customized tasks, profiles and systems which work well together and also provide developers with features like our generator system and Twitter Bower integration. Yeoman takes care of configuring your Gruntfile and setup to support Sass, CoffeeScript and Require.js/r.js out of the box. With additional features like wiring, an improved `server` and `init`, we like to think of ourselves as a helper project on top of Grunt.
+
+Developers are free to continue using any Grunt tasks with Yeoman and there should remain a good level of cross-tool task compatibility.
+
+### How does Yeoman differ from tools like Brunch or BBB?
+
+We love tools like Brunch and Grunt-BBB and feel that they offer a great solution for developers wishing to scaffold with frameworks like Backbone.js and Ember. With the Yeoman generator system, as we've ported over the Rails Generator system to work with Node, we feel we have an interesting opportunity to take application scaffolding in a new direction - one where it's easier for any developer to write scaffolds, support multiple testing frameworks, capture their own boilerplates and easily re-use them and so on.
+
+### How do I register or unregister a package on Bower?
+
+Packages can be registered on Bower using the `register` command. e.g `bower register myawesomepackagename git://github.com/youraccount/yourrepo`. We recommend reading the Bower [documentation](https://github.com/twitter/bower) before doing this to ensure that your repo includes the necessary files to supporting being `install`ed.
-The short-term goals for Yeoman are to provide developers with an improved tooling workflow so that they can spend less time on process and more time focusing on building beautiful web applications. Initially, we hope to make it as easy as possible to work with existing frameworks and tools developers are used to using.
-Long-term, the project may also assist developers with creating applications using modern technologies such as Web Components.
### Will the project be providing Generators for popular frameworks?
Our goal is to facilitate both developers and the community with the tools needed to create rich web applications easily. With that goal in mind, we'll be providing a great API (and docs) to our Generators system with examples of how to implement samples, but will rely on the community to create and maintain Generators for popular frameworks. This will allow us to focus on making Yeoman better without he distractions of maintaining a large number of Generators.
+
### What license is Yeoman released under?
Yeoman is released under a [BSD](http://opensource.org/licenses/bsd-license.php/) license.
+### What should I do before submitting an issue through GitHub?
+
+Thanks for your interest in submitting an issue. In order for us to help you please check that you've completed the following steps:
+
+* Made sure you're on the latest version
+* Read our documentation and [README](https://github.com/yeoman/yeoman/blob/master/readme.md) to ensure the issue hasn't been noted or solved already
+* Used the search feature to ensure that the bug hasn't been reported before
+* Included as much information about the bug as possible, including any output you've received, what OS and version you're on.
+* Shared the output from `echo $PATH $NODE_PATH` and `brew doctor` as this can also help track down the issue.
-### Bower
+Issues can be submitted via the [issues tab](https://github.com/yeoman/yeoman/issues) on our GitHub repo.
-####What distinguishes Bower from Jam, Volo or Ender? What does it do better?
-It's easiest to think of Bower as a lower level component then Jam, Volo, or Ender.
-All Bower really does is install git paths, resolves dependencies from a component.json, checks versions, and then provides api which tells you what it did.
-The major diversion from past attempts at package management in the front-end, is that Bower is working under the assumption that there is a single, common problem in frontend application development which needs to be solved: resolving dependencies and managing components. Unfortunately, most other attempts tried to tackle this problem in such a way that it ends up alienating communities which develop using different transports (sprockets, commonjs, requirejs, regular script tags).
+ is working under the assumption that there is a single, common problem in frontend application development which needs to be solved: resolving dependencies and managing components. Unfortunately, most other attempts tried to tackle this problem in such a way that it ends up alienating communities which develop using different transports (sprockets, commonjs, requirejs, regular script tags).
For example, someone developing with sprockets, can't use volo packages, can't use jam packages, and so forth.
View
3 docs/installation.md
@@ -11,7 +11,7 @@ Installing Yeoman in an easy process that should take less than 10 minutes on OS
Open up a terminal and enter in the following:
```sh
-$ curl https://raw.github.com/yeoman/yeoman/master/setup/install.sh | sh
+$ curl -L get.yeoman.io | sh
```
This will immediately install Yeoman and any dependencies it may need such as Node, NPM and Ruby.
@@ -223,4 +223,5 @@ npm uninstall yeoman -g
So sad to see you go ☹
If it was installed locally, next to your gruntfile, simply drop the
+`node_modules/yeoman` folder.imply drop the
`node_modules/yeoman` folder.
View
3 docs/readme.md
@@ -0,0 +1,3 @@
+# Documentation
+
+The markdown files for our documentation can be found in this directory. These are mirrored in the yeoman.io repository.

0 comments on commit 55af612

Please sign in to comment.
Something went wrong with that request. Please try again.