Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Remove docs. Now available in the wiki.

  • Loading branch information...
commit c020b50831baba4387f52684e935f24af23eddd3 1 parent 3488e6c
@sindresorhus sindresorhus authored
View
2  .npmignore
@@ -2,9 +2,7 @@
.editorconfig
.jshintrc
.gitattributes
-docs
setup
-spec
sublime
test
Gruntfile.js
View
81 docs/cli/commands/build.md
@@ -1,81 +0,0 @@
-## <a href="#build" name="build">build</a>
-
-Usage: `yeoman build`, `yeoman build:<target>`
-
-Constructs an optimized version of your application that's ready to deploy.
-
-Yeoman makes use of [Grunt](https://github.com/gruntjs/grunt) behind the scenes to tackle much of the hard work for this, with some useful additions that assist with compression, optimization and testing.
-
-These include:
-
-* Linting all JavaScript files against JSHint
-* Recompiling all CoffeeScript and SASS files for production
-* Using r.js to compile and optimize any AMD modules
-* Concatenation and minification of scripts and stylesheets
-* Compressing your images using OptiPNG for PNG files and JPEGtran-turbo for JPEGs
-* Running any unit tests written against a headless WebKit browser (via PhantomJS)
-* Creating an Application Cache manifest via Confess.js
-* Using revision filenames or oldernames
-
-Much of the build configuration information for a project is placed inside 'Gruntfile.js', a file which we automatically create when you generate a new project using Yeoman. This file can be fully customized to support which paths you wish to watch, have compiled (should they contain Compass or CoffeeScript files) and so on.
-
-When you run `yeoman server`, we generate an intermediate build directory called `temp`, containing compiled versions of your Compass and CoffeeScript files as well as all of the other files needed to preview your application. Running `yeoman build` creates a `dist` directory which has completely optimized version of your application that can be deployed to staging.
-
-### Build targets
-
-Yeoman supports a number of build targets to be used with `yeoman build`. To implicitly
-pass the `default` target one would run `yeoman build:default` for example. The complete
-list of supported build targets can be found below:
-
-* default: Runs `concat css min img rev usemin manifest`
-* text: Runs `concat css min rev usemin manifest`
-* buildkit: Runs `concat css min img rev usemin manifest html:buildkit`
-* basics: Runs `concat css min img rev usemin manifest html:basics`
-* minify: Runs `concat css min img rev usemin manifest html:compress`
-
-
-### Sub-tasks
-
-Each build target above runs a number of different build *tasks*. The supported
-tasks included with Yeoman out of the box are:
-
-* clean: Wipe the previous build dirs
-* copy: Copies the whole staging(intermediate/) folder to output (publish/) one
-* css: Concatenates, replaces @imports and minifies the CSS files
-* dom: DOM-based build system
-* html: Basic to aggressive HTML minification
-* img: Optimizes .png/.jpg images using OptiPNG/JPEGtran
-* mkdirs: Prepares the build dirs
-* rev: Automate the hash renames of assets filename
-* usemin: Replaces references to non-minified scripts / stylesheets
-
-### Require.js / r.js configuration
-
-Yeoman has a special task that automatically handles the optimization of Require.js/AMD
-projects using the r.js optimizer. Configuration for this optimization (i.e your r.js
-configuration) should be done within the `rjs` section of the Gruntfile for a project.
-
-You can either do this at a project level by editing your projects Gruntfile or do this
-at a generator level if you would rather avoid editing the Gruntfile outside of the default
-setup each time.
-
-The following is the relevant block to edit within your Gruntfile:
-
-```js
-// rjs configuration. You don't necessarily need to specify the typical
-// `path` configuration, the rjs task will parse these values from your
-// main module, using http://requirejs.org/docs/optimization.html#mainConfigFile
-//
-// name / out / mainConfig file should be used. You can let it blank if
-// you're using usemin-handler to parse rjs config from markup (default
-// setup)
-rjs: {
- // no minification, is done by the min task
- optimize: 'none',
- baseUrl: './scripts',
- wrap: true
-}
-```
-
-See the official project [repo](https://github.com/jrburke/r.js) for more information on the
-options supported by r.js.
View
21 docs/cli/commands/help.md
@@ -1,21 +0,0 @@
-## <a href="#help" name="help">help</a>
-
-* `yeoman --help` or `yeoman help`
-
-Lists out the commands and tasks supported by yeoman and should print out the following to the console:
-
-```sh
-yeoman init # Initialize and scaffold a new project using generator templates
-yeoman build # Build an optimized version of your app, ready to deploy
-yeoman server # Launch a preview server which will begin watching for changes
-yeoman test # Run a Mocha test harness in a headless PhantomJS
-
-yeoman install # Install a package from the clientside package registry
-yeoman uninstall # Uninstall the package
-yeoman update # Update a package to the latest version
-yeoman list # List the packages currently installed
-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.
View
106 docs/cli/commands/init.md
@@ -1,106 +0,0 @@
-## <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.
-
-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)
-* RequireHM 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.
-
-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:
-
-```sh
- _ .--------------------------.
- _|o|_ | Welcome to Yeoman, |
- |_| | ladies and gentlemen! |
- / \Y/ \ o_________________________|
- || : |//
- o/ --- \
- _\ /_
-
-Out of the box I include HTML5 Boilerplate, jQuery and Modernizr.
-
-.. Invoke app ..
-
-Please answer the following:
-[?] Would you like to include Twitter Bootstrap for Compass? (Y/n)
-```
-
-### custom generators
-
-Some of our supported custom generators include:
-
-```sh
-yeoman init bbb # backbone boilerplate
-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:
-
-```sh
-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:
-
- 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.
-
-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:
-
- 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:
-
- yeoman init angular:controller controllerName
-
-where `controllerName` is the name of the Controller you wish to create.
-
-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:
-
- yeoman init backbone:model modelName
- yeoman init backbone:collection collectionName
- yeoman init backbone:view viewName
- yeoman init backbone:router routerName
-
-To list out all of the generators currently available locally, you can use the `--help` flag as follows:
-
- yeoman init --help
-
-This will print out a list of existing generators, including some of the below:
-
-```sh
-Please choose a generator below.
-
-Yeoman:
- generator
- controller
-
-Ember:
- ember:all
- ember:controller
- ember:model
- ember:view
-
-Backbone:
- backbone:all
- backbone:model
- backbone:router
- backbone:view
- backbone:collection
-```
View
48 docs/cli/commands/install.md
@@ -1,48 +0,0 @@
-## <a href="#install" name="install">install</a>
-
-Usage: `yeoman install <packageName>`, `yeoman install <package1> <package2>`
-
-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.
-
-By default, running `yeoman install packageName` will install the dependency in your projects `app/components` folder.
-
-Example:
-
-```sh
-yeoman install backbone
-
-# or if you wish to install multiple packages at once..
-yeoman install jquery spine
-```
-
-As mentioned, the files for these dependencies will be added to `app/components`. If you wish to use any of them you will need to manually include a script/file reference to the relevant source files.
-
-Example:
-
-```html
-<script src="components/spine/lib/spine.js"></script>
-```
-
-If installing a dependency which has its own dependencies described, these dependencies will also be pulled in.
-
-Example:
-
- yeoman install backbone
-
-will actually also install Underscore.js and jQuery.js as these are required for Backbone to function correctly.
-
-`yeoman install` also supports installing packages using more than just the package name. Namely:
-
- yeoman install jquery
- yeoman install git://github.com/components/jquery.git
- yeoman install components/jquery (same as above)
- yeoman install http://foo.com/jquery.awesome-plugin.js
- yeoman install ./repos/jquery
-
-As you can see, packages can be installed by name, Git endpoint, GitHub shorthand, URL or local path. If you install and URL that is a zip or tar file, yeoman will automatically extract the contents of it. When tags are available in the endpoint, you can specify a semver tag to fetch concrete versions:
-
- yeoman install jquery#1.8.1
- yeoman install git://github.com/components/jquery.git#~1.8.1
- yeoman install components/jquery#1.8.x
-
-More in the [Bower docs](https://github.com/twitter/bower/blob/master/README.md#usage)
View
26 docs/cli/commands/list.md
@@ -1,26 +0,0 @@
-## <a href="#list" name="list">list</a>
-
-Usage: `yeoman list`
-
-Lists all of the packages that have been installed using `yeoman install` (Bower) in your current project.
-
-Example:
-
-```sh
-# If you have previously called
-yeoman install backbone
-
-# and then run
-yeoman list
-
-# the output will be
-
-/myapp/
-├─┬ backbone#0.9.2
-│ ├── jquery#1.7.2
-│ └── underscore#1.3.3
-├── jquery#1.7.2
-└── underscore#1.3.3
-```
-
-As you can see, this also includes the version information for each package and its dependencies.
View
15 docs/cli/commands/lookup.md
@@ -1,15 +0,0 @@
-## <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`), otherwise `search` should be used for broader queries.
-
-Example:
-
-```sh
-yeoman lookup jquery
-
-# outputs
-
-jquery git://github.com/maccman/package-jquery.git
-```
View
19 docs/cli/commands/search.md
@@ -1,19 +0,0 @@
-## <a href="#search" name="search">search</a>
-
-Usage: `yeoman search <keyword>`
-
-Searches the Bower registry for packages which include a specific keyword in their name.
-
-Example:
-
-```sh
-yeoman search jquery
-
-# outputs
-
-Search results:
-
- - jquery git://github.com/maccman/package-jquery.git
- - jquery-ui git://github.com/maccman/package-jquery-ui.git
- - jquery-infinite-scroll git://github.com/paulirish/infinite-scroll.git
-```
View
30 docs/cli/commands/server.md
@@ -1,30 +0,0 @@
-## <a href="#server" name="server">server</a>
-
-Usage: `yeoman server`
-
-Launches a preview server on port 3501 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
-LiveReload installed locally, a fallback reload process will be used instead.
-
-Any changes to CoffeeScript or Compass files result in them being recompiled, meaning that
-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`.
-
-To quit the server, simply use `ctrl+c` and this will kill the Yeoman server process.
-
-### profiles
-
-The built-in server also supports serving different profiles of your application, such as: `app`, `dist`, `test` and `reload`.
-
-* `yeoman server` and `server:app` compile to and serve `/temp`, an intermediate build of your application.
-* `yeoman server:dist` serves up the optimized final version of your application. This will just serve up the `/dist` directory if it exists and you will need to run `yeoman build` in order to generate the production build of your app.
-* `yeoman server:test` serves up the test suite and your `app`. It also ensure any change to your code or tests will cause the browser to refresh.
-* `yeoman server:reload` forces the port to be LiveReload standard port: 35729 and prevents the automatic default browser opening. Handy for those wishing to use livereload extensions with other systems / HTTP servers than the one provided by Yeoman out of the box.
-
-### further notes
-
-At present, when initially running `yeoman server` or `yeoman server:app`, some users may find that their browser is opened before intermediate files such as Compass and CoffeeScript have completed compiling. Whilst we intend on fixing this issue very soon, in the mean time we recommend refreshing the browser shortly after you first fire up the server (e.g 10 seconds after). You can then easily make any changes you wish to your application and the browser will be automatically reloaded via LiveReload.
View
30 docs/cli/commands/test.md
@@ -1,30 +0,0 @@
-## <a href="#test" name="test">test</a>
-
-Usage: `yeoman test`
-
-Runs a Mocha test harness in a headless instance of PhantomJS.
-
-When you generate a new project using `yeoman init`, we also scaffold out a basic set of
-Mocha unit tests that you can continue using to test your application.
-
-Running `yeoman test` allows you to easily check if all of your tests are passing. This also
-gets called when running `yeoman build`.
-
-A dedicated server, with visibility on `app`, `temp` and `test` is
-launched to serve file for PhantomJS.
-
-
-Example:
-
-```sh
-yeoman test
-
-# outputs:
-
-Running "mocha:all" (mocha) task
-Running specs for index.html
-.....................................................
->> 82 assertions passed in 53 specs (562ms)
-
-Done, without errors.
-```
View
28 docs/cli/commands/uninstall.md
@@ -1,28 +0,0 @@
-## <a href="#uninstall" name="uninstall">uninstall</a>
-
-Usage: yeoman uninstall packageName
-
-Removes the package `packageName` from the current project.
-
-Example:
-
-```sh
-yeoman uninstall backbone
-
-# outputs:
-
-bower uninstalling /project/components/backbone
-```
-
-Note: If you attempt to uninstall a package that is a dependency of other packages, yeoman (via Bower) will throw an error.
-
-Example:
-
-```sh
-yeoman uninstall jquery
-
-# outputs:
-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.
View
16 docs/cli/commands/update.md
@@ -1,16 +0,0 @@
-## <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.
-
-Example:
-
-```sh
-yeoman update jquery
-
-# outputs
-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.
View
690 docs/cli/generators.md
@@ -1,690 +0,0 @@
-## <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.
-
-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
-
-yeoman init generator
-----------------------
-
-The `yeoman init` command uses templates and prompts to create the files needed for a project.
-
-Running `yeoman init --help` by itself gives a list of available generators:
-
- $ yeoman init generator
- Usage: yeoman init generator GENERATOR [args] [options]
-
- ...
- ...
-
- Please choose a generator below.
-
- Yeoman:
- controller
- generator
- ...
- ...
-
-**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**: 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 generator controller NAME one two three [options]
-
- Options:
- -h, --help # Print generator's options and usage
- --js-framework # Js framework to be invoked
- # Default: ember
-
-
-The controller generator is expecting parameters in the form of `generate controller ControllerName action1 action2`
-
-Let's make a `Greeting` controller with an action of `hello`.
-
- $ yeoman init generator controller Greeting hello
-
-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
-
-
-Creating and Customizing Yeoman Generators & Templates
-------------------------------------------------------
-
-1. First Contact
-2. Creating Your First Generator
-3. Creating Generators with Generators
-4. Generators Lookup
-5. Customizing Your Workflow
-6. Customizing Your Workflow by Changing Generators Templates
-7. Adding Generators Fallbacks
-8. Application Templates
-
-
-### First contact
-
-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 --help`:
-
- $ yeoman init
- $ cd app
- $ 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 generator [generator] --help
-
-### Creating Your First Generator
-
-Generators are built on top of Grunt. Grunt provides powerful options parsing and a great API for manipulating files. For instance, let’s build a generator that creates an initializer file named initializer.js inside `app/js/`
-
-The first step is to create a file at `lib/generators/initializer/index.js with
-the following content:
-
-```js
-var util = require('util'),
- yeoman = require('../../../');
-
-module.exports = Generator;
-
-function Generator() {
- yeoman.generators.Base.apply(this, arguments);
-}
-
-util.inherits(Generator, yeoman.generators.Base);
-
-Generator.prototype.createInitializerFile = function() {
- 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
-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:
-
-- any method beginning with the `_` prefix.
-- a `constructor` method, specifically used with generators written in
- CoffeeScript
-
-Finally, we invoke the `write` method that will create a file at the given destination with the given content.
-
-**Note**: Generators should execute their tasks synchronously. We currently lack the API to be able to do things asynchronously (which we might need). A
-`this.async()` method should be implemented, which returns a new handler to call on completion.
-
-Now, we can see that the initializer generator available to use if we output
-the list of available generators in this application:
-
- $ yeoman init generator
-
- Usage: yeoman generate GENERATOR [args] [options]
- ...
-
- Please choose a generator below.
-
- ...
-
- Initializer:
- initializer
-
-To invoke our new generator, we just need to do:
-
- $ yeoman init initializer
-
-Before we go on, let’s see our brand new generator description:
-
- $ yeoman generate initializer --help
- .. Invoke initializer ..
- 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:
-
-```js
-var util = require('util'),
- yeoman = require('../../../');
-
-module.exports = Generator;
-
-function Generator() {
- yeoman.generators.Base.apply(this, arguments);
-
- this.desc('This generator creates an initializer file at app/js/');
-}
-
-util.inherits(Generator, yeoman.generators.Base);
-
-Generator.prototype.createInitializerFile = function() {
- this.write('app/js/initializer.js', "// Add initialization content here");
-};
-```
-
-Now we can see the new description by invoking --help on the new generator. The second way to add a description is by creating a file named `USAGE` in the same directory as our generator. We are going to do that in the next step.
-
-### Creating Generators with Generators
-
-Generators themselves have a generator:
-
- $ yeoman init generator initializer
- create lib/generators/initializer
- create lib/generators/initializer/index.js
- create lib/generators/initializer/USAGE
- create lib/generators/initializer/templates
-
-This is the generator just created:
-
-```js
-var util = require('util'),
- yeoman = require('../../../');
-
-module.exports = Generator;
-
-function Generator() {
- yeoman.generators.NamedBase.apply(this, arguments);
-
- this.sourceRoot(__dirname, 'templates');
-}
-
-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`.
-
-We can see that by invoking the description of this new generator:
-
- $ yeoman init initializer --help
-
- 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.
-
-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).
-
-In order to understand what a generator template means, let’s create the file
-lib/generators/initializer/templates/initializer.js with the following content:
-
- // Add initialization content here
-
-And now let’s change the generator to copy this template when invoked:
-
-```js
-var util = require('util'),
- yeoman = require('yeoman');
-
-module.exports = Generator;
-
-function Generator() {
- yeoman.generators.NamedBase.apply(this, arguments);
- // if your templates/ location differ, feel free to set it with sourceRoot()
-}
-
-util.inherits(Generator, yeoman.generatos.NamedBase);
-
-Generator.prototype.copyInitializerFile = function() {
- this.copy('initializer.js', 'config/initializers/' + this.name + '.js');
-};
-```
-
-And let’s execute our generator:
-
- $ yeoman init initializer core_extensions
-
-We can see that now an initializer named `core_extensions` was created at
-`config/initializers/core_extensions.js` with the contents of our template. That
-means that `copy` copied a file in our source root to the destination path
-we gave. The property `name` is automatically created when we inherit from
-`yeoman.Generators.NamedBase`, and match the value of the given argument
-(`NamedBase` automatically specify an argument via `this.argument`)
-
-### Generators Lookup
-
-When you run `yeoman init initializer core_extensions` yeoman requires these
-paths in turn until one is found:
-
- lib/generators/initializer/index.js
- lib/generators/initializer.js
- lib/generators/yeoman/initializer/index.js
- lib/generators/yeoman/initializer.js
-
-**Note**: `index.js` may be anything else, as long the module entry point is
-defined in a package.json.
-
-**Second Note**: While true, the help output might miss a generator. It looks
-for file below lib/generators at few locations, searching for `index.js` files.
-
-yeoman will do this lookup at few different places, in this order:
-
-- relative to the working directory, from within a yeoman application.
-- relative to any `node_modules/yeoman-*` module. These are called "yeoman
- plugins", they should package up their generator in the `lib/generators`
- directory.
-
-This mean that users may override part or the whole set of generator used by
-yeoman, either at an application level, with custom handcrafted generator or
-via "yeoman plugin" (a node package that defines a set of generators in their
-`lib/generators` directory).
-
-If none is found you get an error message.
-
-### Customizing your Workflow
-
-Yeoman own generators are flexible enough to let you customize scaffolding. They
-can be configured in your application Gruntfile, these are some defaults:
-
-```js
-generators: {
- 'template-engine': 'handlebars',
- 'test-framework': {
- name: 'mocha',
- options: {
- ui: 'bdd'
- }
- }
-}
-```
-
-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.
-
-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.
-
-**TBD** Finish up this section: example of running controller generator, see
-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`.
-
-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.
-
-
-### More On Generators
-
-So we know that a typical generator looks like the following:
-
-```js
-var util = require('util'),
- yeoman = require('../../../');
-
-module.exports = Generator;
-
-function Generator() {
- yeoman.generators.NamedBase.apply(this, arguments);
-}
-
-util.inherits(Generator, yeoman.generators.NamedBase);
-
-Generator.prototype.createSomething = function() {
- // code
-};
-
-// ... other methods ...
-```
-
-Generators can also be written in CoffeeScript, they just needs to be named with a `.coffee` extension (typically `lib/generators/generatorName/index.coffee`)
-
-```coffee
-yeoman = require 'yeoman'
-
-module.exports = class Generator extends yeoman.generators.NamedBase
-
- constructor: (args, options, config) ->
- super args, options, config
-
- createSomething: ->
- # code
-
- # ... other method ...
-```
-
-They're usually layout like so:
-
- lib/
- └── generators
- └── generatorName
- ├── USAGE
- ├── index.js
- └── templates
-
-Generators extends either `yeoman.generators.Base` or `yeoman.generators.NamedBase`. `NamedBase` is suitable to use for generators 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.
-
-Two exceptions:
-
-- any method beginning with `_` is not ran, you may use them as method
- helper. They won't be called automatically on generator invocation.
-- 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 / ...)
-
-grunt.file
-----------
-
-Generators get mixed into their prototype the [grunt.file](https://github.com/gruntjs/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`.
-
-`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/gruntjs/grunt/blob/master/docs/api_log.md#the-log-api) API as `this.log`
-
-
-```js
-Generator.prototype.doingSomething = function() {
- this.log.writeln('I\'m doing something');
- this.log.ok('.. And I think it's ok ..'');
-};
-```
-
-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.
-
-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.
-
-It this method isn't invoked, the method executes synchronously.
-
-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/gruntjs/grunt/blob/master/docs/api_file.md#the-file-api
-
-**TBD**
-
-## Base Generator
-
-A `Base` generator has the following methods, members, and events.
-
-### generator.options
-
-A hash object holding all cli parsed options by nopt.
-
-### generator.argument(name, options)
-
-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:
-
- 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).
-
-Options:
-
-* desc - Description for the argument.
-* required - If the argument is required or not.
-* optional - If the argument is optional or not.
-* type - The type of the argument, can be String, Number, Array, Object
- (in which case considered as an Hash object, key:value).
-* defaults - Default value for this argument. It cannot be required
- and have default values.
-* banner - String to show on usage notes.
-
-### generator.option(name, options)
-
-Adds an option to the set of generator expected options, only used to
-generate generator usage. By default, generators get all the cli option
-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.
-
-### 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.
-
-By default, takes the value of `templates/` next to the generator file.
-
-When no path is given, returns the value of `_sourceRoot`.
-
-### generator.destinationRoot([path])
-
-Sets the destination root for this class, ensure the directory is created and
-cd into it.
-
-### generator.hookFor(name, options)
-
-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.
-
-```js
-function MyGenerator(args, options, config) {
- yeoman.generators.Base.apply(this, arguments);
- // init a framework specific controller
- this.hookFor('js-framework');
-}
-```
-
-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.
-
-For example, if the user invokes the controller generator as:
-
- yeoman init controller Account --js-framework backbone
-
-The controller generator will then try to invoke the following generators:
-
- "backbone:controller" "backbone"
-
-Notice that the value of a given hook can be defined in your application Gruntfile as well:
-
-```js
-// grunt config
-generators: {
- 'js-framework': 'backbone'
-}
-// ... more grunt config ...
-```
-
-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:
-
-- `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:
-
-```js
-// in lib/generators/awesome/index.js generator's constructor.
-this.hookFor('test-framework');
-```
-
-The lookup in this case for test_unit as input is:
-
- "test_framework:awesome", "test_framework"
-
-(more specifically, `"jasmine:awesome", jasmine"` which is the default value
-for `test-framework` hook)
-
-Which is not the desired lookup. You can change it by providing the `as` option:
-
-```js
-// in lib/generators/awesome/index.js generator's constructor.
-this.hookFor('test-framework', { as: 'controller' });
-```
-
-And now it will lookup at:
-
- "test_framework:controller", "test_framework"
-
-### generator.copy(source, destination, options)
-
-> Copy a source file to a destination path, creating intermediate directories if necessary.
-
-Grunt's [`grunt.file.copy`](https://github.com/gruntjs/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
-var source = path.join(this.sourceRoot(), 'path/to/file.js');
-grunt.file.copy(source, destination, options);
-```
-
-### generator.read(filepath, [encoding])
-
-Same as copy, `.read()` relative `filepath` are prefixed by `self.sourceRoot()`
-value.
-
-### generator.write(filepath, [encoding])
-
-> Write the specified contents to a file, creating intermediate directories if necessary.
-
-Just like
-[`grunt.file.write`](https://github.com/gruntjs/grunt/blob/master/docs/api_file.md#grunt-file-write),
-we simply ensure the log output of the files being written.
-
-```js
-// similar to
-grunt.option('verbose', true);
-grunt.file.write(filepath, encoding);
-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.
-
-```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.
-
-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.
-
-Each file is copied and processed through `grunt.template.process`.
-
-```js
-this.directory('.', 'test');
-```
-
-The example above copies and process any files within generators `templates/`
-directory, and write them at the `test/` location.
-
-### generator.tarball(url, destination, cb)
-
-Fetch a remote tarball, and untar at the given destination.
-
-```js
-this.tarball('https://github.com/twitter/bootstrap/tarball/master', 'vendor/bootstrap', this.async());
-```
-
-### generator.fetch(url, destination, cb)
-
-Download a single file at the given destination.
-
-```js
-this.fetch('http://zeptojs.com/zepto.js', 'js/vendor/zepto.js', this.async());
-```
-
-### generator.remote(username, repository, [branch], cb)
-
-Remotely fetch a package on github, store this into an internal `_cache/`
-folder, and invokes provided callback on completion with a "remote" object as
-the main API to interact with downloaded package.
-
-- username - GitHub username
-- repository - GitHub repository to fetch from
-- branch - Optional branch or sha1, defaults to master
-- cb - function to invoke on completion
-
-The example below downloads and cache the html5-boilerplate project, and use the `remote` object
-to copy the whole project into the `app/` folder.
-
-```js
-var cb = this.async();
-this.remote('h5bp', 'html5-boilerplate', 'master', function(err, remote) {
- if(err) return cb(err);
- // remote.copy('index.html', 'index.html');
- // remote.template('index.html', 'will/be/templated/at/index.html');
- remote.directory('.', 'app');
- cb();
-});
-```
-
-`remote()` allows the download of full repositories and copying of single or
-multiple files. `remote` object is your API to access this fetched (and cached)
-package and copy / process files.
-
-#### remote.copy(source, destination, options)
-
-Same as `generator.copy()` but relative `source` is prefixed with the cache
-directory.
-
-#### remote.template(source, destination, options)
-
-Same as `generator.temlate()` but relative `source` is prefixed with the cache
-directory.
-
-#### remote.template(source, destination, options)
-
-Same as `generator.directory()` but relative `source` is prefixed with the cache directory.
-
-
-#### Prompt user before overwriting files with `--force`
-
-Generators also support a `warnOn` method, which allows developers to warn on global paths that are matching those paths or files which the generator is going to generate (e.g `self.warnOn('*')`.
-
-Where used, Yeoman will warn the user they if they proceed that a file will be overwritten and they may need to call the generator with the `--force` flag to proceed.
-
-`warnOn` is most likely to be used in constructors.
View
368 docs/cli/modules.md
@@ -1,368 +0,0 @@
-## <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.
-
-Yeoman comes with experimental support for ES6 modules, made possible through Require HM. HM allows us to write ES.next module syntax and as long as code is saved in files with `.hm` extension, they can be used with RequireJS and AMD as if they were regular ES3/5 scripts.
-
-
-*Note: The ES.next module specification is not yet complete and is subject to change. As such, the material below should be considered correct as of June, 2012 but for later dates the Harmony wiki entry on modules should be consulted to ensure correctness.
-
-Also note that as Require HM is a RequireJS plugin, ES6 modules are only supported when used with RequireJS. We hope to change this in the future once support for ES6 modules in Google Traceur has improved.*
-
-### module:
-
-In ES6, A module is a unit of code contained within a `module` declaration. It can either be defined inline or within an externally loaded module file. A skeleton inline module for a Car could be written:
-
-```js
-module Car{
- // import …
- // export …
-}
-```
-
-When we say *externally loaded modules*, we are referring to modules which are either loaded using `import` declarations or the Module Loader API. Both will be covered shortly.
-
-A module *instance* is a module which has been evaluated, is linked to other modules or has lexically encapsulated data. Examples of modules instances are:
-
-```js
-module myCar = Car;
-module myCar at "car.js";
-```
-
-`module` declarations can be used in the following contexts:
-
-```js
-module Universe {}
-module Universe { module MilkyWay {} }
-module MilkyWay = "Universe/MilkyWay"
-module System = Universe.MilkyWay.SolarSystem
-module System = SolarSystem
-```
-
-### export:
-
-An export declaration declares that a local function or variable binding is visible externally to other modules. If familiar with the module pattern, think of this concept as being parallel to the idea of exposing functionality publicly.
-
-```js
-module Car{
-
- // Internals
- var licensePlateNo = "556-343"
-
- // Exports
- export function drive(speed, direction){
- console.log('We are driving at a speed of ' + speed + ', ' + direction);
- }
-
- export var miles = 5000;
- export var color = "silver";
-}
-```
-
-Modules `import` what they wish to use from other modules. Other modules may read the module exports (e.g `drive()`, `miles` etc. above) but they cannot modify them. Exports can be renamed as well so their names are different from local names.
-
-A module may also export other modules for consumption.
-
-```js
-module Car{
- export module engine{}
- export module driver{}
- export module seats{}
-}
-```
-
-`export` can be used in the following contexts:
-
-```js
-export var document
-export var document = { }
-export function parse() { }
-export module System = SolarSystem
-export SolarSystem
-export Mercury, Venus, Earth
-export * from SolarSystem
-export { Mercury: SolarSystem.Mercury, Earth: SolarSystem.Earth }
-```
-
-### import:
-
-An import declaration binds another modules exports as local variables. Variables that are imported can be locally renamed to avoid naming conflicts.
-
-```js
-module Car{
- export function drive(speed, direction){
- console.log('details:', speed, direction);
- }
-
- export module engine{
- export function check(){ ... }
- }
-
- export var miles = 5000;
- export var color = "silver";
-
-};
-```
-
-Revisiting the export example above, we can now selectively choose what we wish to `import` when in another module.
-
-We can just import `drive()`:
-
-```js
-import drive from Car;
-```
-
-We can import `drive()` and `miles`:
-
-```js
-import {drive, miles} from Car;
-```
-
-We can import `check()` from our engine module:
-
-```js
-import check from Car.engine;
-```
-
-We can import all of the exports:
-
-```js
-import * from Car;
-```
-
-We can also import an entire file as a module:
-
-```js
-import "car.js" as Car;
-```
-
-Or import `drive()` without needing to bind the module to a local name:
-
-```js
-import drive from "car.js";
-```
-
-This similarly works with JavaScript libraries like Underscore.js:
-
-```js
-import reduce from "Underscore.js"
-```
-
-
-### module, import and export
-
-Bringing these three concepts together:
-
-```js
-module vehicle{
- export function drive(speed, direction){
- console.log('We are driving at a speed of ' + speed + ', ' + direction);
- };
-
- export function stop(){
- console.log('We have stopped');
- };
-
- export var miles = 0;
- export var color = "silver";
- export var wheels = 4;
-}
-
-module basicExtras{
- export var carSeat = true;
- export var specialRims = true;
- export var mp3Player = true;
-}
-
-module premiumExtras{
- export module GPS{
- //...
- }
-}
-```
-
-```js
-// Engine.js
-module engine{
-
-}
-```
-
-```js
-module Car{
- import * from vehicle;
- import {specialRims, mp3Player} from basicExtras;
- import "engine.js" as engine;
- module navigationSystem from premiumExtras.GPS;
-
- export drive;
- export stop;
-}
-```
-
--- how do you rename exports?
-
-
-
-### dynamically loading modules
-
-Earlier, we mentioned the concept of a Module Loader API. The module loader allows us to dynamically load in scripts for consumption. Similar to `import`, we are able to consume anything defined as an `export` from such modules.
-
-```js
-// Signature: load( moduleURL, callback, errorCallback )
-
-Loader.load("car.js", function(car) {
- console.log(car.drive(500, "north"));
- }, function(err){
- console.log("Error:" + err);
- });
-```
-
-`load()` accepts three arguments:
-
-* moduleURL: The string representing a module URL (e.g "car.js")
-* callback: A callback function which receives the output result of attempting to load, compile and then execute the module
-* errorCallback: A callback triggered if an error occurs during loading or compilation
-
-Whilst the above example seems fairly trivial to use, the Loader API is there to provide a way to load modules in controlled contexts and actually supports a number of different configuration options. `Loader` itself is a system provided instance of the API, but it's possible to create custom loaders using the `Loader` constructor.
-
-```js
-// The Loader constructor creates a new loader
-var customLoader = new Loader(
- // Define the parent of this loader
- // if a custom one exists, otherwise
- // just use the default system Loader
- Loader, {
-
- // Global object for the Loader
- global: Object.create(null),
-
- // Loader's base URL
- baseURL: baseURL,
-
- // A flag indicating whether code should be evaluated
- // in strict mode
- strict: false,
-
- // Source of the loader intrinsics which can either
- // be an existing loader or just null
- linkedTo: Loader || null,
-
- // The module resolution hook
- resolve: function( relativeURL, baseURL ){..},
-
- // The module loading hook
- fetch: function( relativeURL, baseURL, request, resolved ){…},
-
- // A hook for source translation
- translate: function( src, relativeURL, baseURL, resolved ){…}
-});
-```
-
-Let's review the final three hooks in more detail:
-
-**fetch: function( relativeURL, baseURL, request, resolved ):**
-
-Once a module is resolved, it must be fetched. The `fetch` hook allows us to fetch code from an external resource and returns its source via the first callback or rejecting the code via the second callback.
-
-
-The `fetch` request object has three callbacks:
-
-```js
-request = {
-
- // callbacks for the loading hook
-
- // callback to create the successfully loaded source
- fulfill: function( src ){..},
-
- // callback to indicate the source should be loaded from a different URL
- redirect: function( url, baseURL ){..}
-
- // callback to indicate am error occurred in the loading
- reject: function( msg )
-}
-```
-
-If we don't supply a `fetch` hook, the parent Loader's `fetch` is used instead.
-
-
-
-**resolve: function( relativeURL, baseURL ):**
-
-
-
-**translate: function( src, relativeURL, baseURL, resolved ):**
-
-When code is evaluated, we have the option of translating the source of that code using this hook. The hook can either produce the final source code or throw an exception if something goes wrong.
-
-
-A complete custom loader example could thus be written as follows:
-
-```js
-var customLoader = new Loader(Loader,{
- global: window,
- baseURL: document.URL.substring(0, document.URL.lastIndexOf('\/') + 1),
- strict: false,
- resolve: function (relURL, baseURL) {
- var url = baseURL + relURL;
- return url;
- },
- fetch: function (relURL, baseURL, request, resolved) {
- var url = baseURL + relURL;
- var xhr = new XMLHttpRequest();
- xhr.onreadystatechange = function () {
- if (xhr.readyState === 4) {
- if (xhr.status === 200) {
- request.fulfill(xhr.responseText);
- } else {
- request.reject(xhr.statusText);
- }
- }
- };
- xhr.open("GET", url, true);
- xhr.send(null);
- },
- translate: function (src, relURL, baseURL, resolved) {
- return src;
- }
- });
-```
-
-
-*Note: As Require HM is able to work with the RequireJS `define()` and `require()` syntax, it doesn't currently support the Module Loader API. If one is however required, there is a shim available for this feature [here](https://github.com/addyosmani/es6-module-loader/).*
-
-
-### What else can be done with modules?
-
-We can also define modules with a shared state:
-
-```js
-module Car{
- export module milesCounter {
- var miles = 0;
- export function addMile() { return miles++ }
- export function currentMiles() { return miles }
- };
-};
-```
-
-or cyclic dependencies:
-
-```js
-module Car {
- import * from Scooter;
- export function even(n) {
- return n == 0 || odd(n - 1);
- }
-}
-
-module Scooter {
- import * from Car;
- export function odd(n) {
- return n != 0 && even(n - 1);
- }
-}
-```
-
-*Note: Require HM does not presently support cyclic dependencies. We are working on fixing this limitation.*
View
95 docs/cli/package_manager.md
@@ -1,95 +0,0 @@
-# Package Manager
-
-Until now, client-side JavaScript has not benefited from a rich package management solution such as those found in other platforms (e.g NPM, RubyGems). By instead maintaining packages of packages in client-side JS, developers reduced the chances of using up-to-date versions of libraries.
-
-Yeoman's integration with [Twitter Bower](http://github.com/twitter/bower) changes that.
-
-In Bower, dependencies are listed in a ‘component.json’ file, similar to Node’s package.json or the Ruby Gemfile. This is useful for locking down the dependencies a project has.
-
-
-```json
-{
- "name": "myProject",
- "version": "1.0.0",
- "dependencies": {
- "modernizr": "~2.6.1"
- }
-}
-```
-
-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:
-
- /component.json
- /components/modernizr/index.js
- /components/modernizr/modernizr.js
-
-This approach has a number of benefits.
-
-* There are no system wide dependencies and no dependencies are shared between different applications
-* None of this is JavaScript specific. Packages can contain JavaScript, CSS, images etc
-* None of this is specific to a specific module format (e.g AMD/CommonJS). These formats can be used but aren't required
-* The dependency tree is flat meaning that we don't ship multiple versions of say, Modernizr to clients
-
-
-The easiest approach is to use a Bower package statically is to then just reference the package manually from a script tag:
-
-```html
-<script src="components/modernizr/modernizr.js"></script>
-```
-
-Similar to NPM, our Bower integration also allows users to easily search for and update packages easily. e.g
-
-To search for a package:
-
- yeoman search jquery
-
-To install a package:
-
- yeoman install jquery
-
-To update a package, you need to reference it by name:
-
- yeoman update jquery
-
-To list installed packages:
-
- yeoman list
-
-and so on.
-
-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 than 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 – use a 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 their 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 its frontend architecture onto Bower, so it's fairly safe to say it will be maintained.
View
89 docs/faq.md
@@ -1,89 +0,0 @@
-# FREQUENTLY ASKED QUESTIONS
-
-
-### What are the goals of the project?
-
-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?
-
-A command-line interface is a means for developers to interact with a system using text commands. On OSX this this is often done using the Terminal and on Windows we use the command shell or a third-party tool such as [Cygwin](http://www.cygwin.com).
-
-
-### What is a package manager?
-
-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.
-
-
-### 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.
-
-
-
-### 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.
-
-Issues can be submitted via the [issues tab](https://github.com/yeoman/yeoman/issues) on our GitHub repo.
-
-
-
-
- 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 their 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.
-
View
132 docs/insight/index.md
@@ -1,132 +0,0 @@
-#Yeoman Insight
-
-##Overview
-
-Yeoman Insight is the metrics reporting tool used by the Yeoman CLI to record and report aggregated usage of the project. From day one (ground zero), we aim to be metrics driven. Having insight into what people are doing with our tool will help measure success of the project and steer its future direction.
-
-##Things to measure
-
-There are a number of useful questions we can answer with good metrics:
-
-- number of downloads
- - Users install Yeoman from the command line (`$ curl -L get.yeoman.io | bash`). We record a "download" page view when the CLI is run for the first time. This is essentially equivalent to the # of installs. Users are unlikely to run the install command and never execute a yeoman task.
- - *Note: Github does not provide a way to track # of .zip/.tar.gz downloads from the project page.*
-- 7, 14, 30-day actives
-- How many people created a project in the last 30 days?
-- What commands/actions are most useful? Which are least popular?
-- What locales are using the tool?
-- How long does it take for developers to upgrade to a new version?
-- What JS frameworks are people using?
-- Imagine: We just launched Yeoman v2.0 @ AwesomeConf JS 2013. Of course it was picked up by Hacker News! Pssht. But...how many new installs did we drive?
-
-Turns out, [Google Analytics](http://www.google.com/analytics/) is excellent at handling all of these cases.
-
-##Collection Workflow
-
-###Backend
-
-Google Analytics suits most of our needs. It was designed to allow any type of app (mobile, non-web page properties, installed apps, etc.) to send data to Analytics for processing. It works similar to the existing API, with the exception that cookies are no longer required.
-
-There are a many benefits to using Analytics instead of rolling our own collecting server on App Engine. Perhaps the biggest: not having to process data ourselves.
-
-###yeomaninsight.py
-
-`yeomaninsight.py` is the brains behind the operation, located in the `/cli/bin` folder:
-
- ├── bin
- │ └── yeomaninsight.py
- │ └── …
-
-> *Note: /metrics was originally setup as an App Engine Python app before Analytics was chosen as backend. At this time, we don't need a separate server but the code is intact if/when we decide to build a dashboard for Yeoman.*
-
-This script is installed globally as an alias `_yeomaninsight` to prevent users from a.) seeing the script via auto completing "yeoman*" and b.) mitigating running the script directly. The script is responsible for collecting, stashing, and sending usage data to Google Analytics.
-
-`_yeomaninsight` is invoked by `/cli/lib/plugins/insight.py`, which creates a folder in the home directory (`~/.yeoman/insight/`) when the cli is run for the first time and prompts the user to opt-in to sending anonymous metrics.
-
-###Recording actions
-
-When users run Yeoman CLI commands, the CLI captures the [sub]commands that were issued by calling `yeomaninsight.py`'s record API. The installed package version and name are also passed as flags. yeomaninsight.py then writes the task to an offline logfile named .log (created on first-run of `yeomaninsight.py`). The format of the file is:
-
- CLIENTID
- TIMESTAMP command
- TIMESTAMP command subcommand
- …
-
-This file is created and saved to the user's home directory (`~/.yeoman/insight/.log`).
-
-####Example run:
-
- $ yeoman init
- -> calls "_yeomaninsight -n yeoman -v 0.9.3 record init"
-
-This creates .log, logs the download on first run, and appends the command:
-
-<table>
-<tr><td>Directory structure</td><td>.log</td></tr>
-<tr><td><pre>
-├── ~/.yeoman/insight/
-│ └── .log
-</pre></td><td>
-<pre>
-1336617026.860.421519437366
-1336617031.37 /downloaded
-1336617031.37 /init
-</pre>
-</td></tr>
-</table>
-
-Running a more complicated command also works:
-
- $ yeoman add model MyModel
- -> calls "_yeomaninsight.py -n yeoman -v 0.9.3 record add model myModel"
-
- .log contains:
- 1336617026.860.421519437366
- 1336630501.37 /add/model
-
-Notice that
-
-1. Space separated commands are joined by "/"s to form a fake URL path. This simulates a pageview to record in Analytics.
-- Personalized information like the name of the model being created ("myModel") is not recorded or sent.
-
-####Why a log file?
-
-The alternative to stashing actions in .log would be to send live requests to Analytics as commands were issued. The main drawback with that approach is that the tool cannot be used offline. I want to use Yeoman on a plane, bro!
-
-###Sending data
-
-`yeomaninsight.py` is also responsible for sending the log data to Analytics. We attempt to send data on every command that is run. If a connection is not present, the data is logged to .log and continues to stash until a successful request to Analytics is made. This potentially means that someone could run the CLI once and not use it again for a few hours. That's ok. The timestamp in the log file is sent with the request to Analytics, allowing it to correctly process older results.
-
-> *Note: Analytics has a maximum of 24hrs that you can send past data. If a user has data and runs yeoman after this period is up, we'll lose those actions. There's nothing that can be done about this. It's a limitation of the Analytic backend.*
-
-After a entries are processed, they're immediately removed from the log file.
-
-####Analytics request format
-
-A command is recorded as a "pageview" in Analytics. yeomaninsight.py makes GET requests to the Analytics endpoint, with the relevant parameters included.
-
-####Example
-
-Eric fires up Yeoman for the first time in 4hrs and runs a few commands:
-
- $ yeoman install jquery
- -> calls "_yeomaninsight.py -n yeoman -v 0.9.3 record install jquery"
- $ yeoman install angular
- -> calls "_yeomaninsight.py -n yeoman -v 0.9.3 record install angular"
-
-The CLI logs each of these entries and sends them to Analytics. This kicks off a call to `_send_all()`, which uploads everything in the log file. If the user is offline ((the first request to Analytics fails) when the upload is triggered, existing log data is kept intact until the next run of the CLI when they're online.
-
-Once all data is sent, `.log` is scrubbed clean of past data, although the Client ID is preserved:
-
- 1336617026.860.421519437366
-
-###Privacy
-
-Our implementation uses Google Analytics. See their [TOS/Privacy Policy](http://www.google.com/analytics/learn/privacy.html) (e.g. Google's Privacy Policy) for more information. There are a few points worth calling out:
-
-- Recording stats are opt-out. This is determined on first-run of the CLI.
-- We eventually plan to open up the collected data to the public. Everyone will benefit!! We plan to have a metrics dashboard where folks can see the data, as collected by the tool.
-- The Client ID is generated as combination of timestamp + random_number and is in no way tied to personal data like IP address, name, location, or other personally identifiable information. Google Analytics uses this data (in aggregate) in order to differentiate users of an app. It allows us to answer the question: "# of 7 day active users".
-- Data is sent to Analytics, an aggregate collection service. There will be no way for us to see information on any one person.
-- We are not recording names of things that were created (e.g. someone's model name, file naming conventions, etc.)
-
View
52 docs/installation.md
@@ -1,52 +0,0 @@
-
-# Installation
-
-Installing Yeoman in an easy process that should take less than 10 minutes on OS X. We also provide notes on how to install on Linux or opt for a more custom installation, should you need to do this. At present, Yeoman is not supported on Windows (but we're working on it!).
-
-## Step 1: Install me
-
-Open up a terminal and enter in the following:
-
-```
-$ curl -L get.yeoman.io | bash
-```
-
-This will audit your system and see what of Yeoman's dependencies are currently installed, such as Node, NPM and Ruby.
-
-This script will give you instructions on how to install what's missing. You're welcome to follow along at the more detailed [Yeoman install procedure](https://github.com/yeoman/yeoman/wiki/Manual-Install).
-
-### Troubleshooting
-There are some [extra troubleshooting guides](https://github.com/yeoman/yeoman/wiki/Additional-FAQ) available, as well.
-
-## Step 2: Create a new project
-
-Next, create a new directory to contain your Yeoman project, then enter in `yeoman init`.
-
-```
-$ mkdir myapp && cd myapp
-$ yeoman init
-```
-
-## Step 3: Profit
-
-We'll then ask you some questions to help scaffold your project out. Simple!
-
-
-# Updating
-
-One of our goals is to implement an easy way to update to the latest version of Yeoman with minimal effort
-on your part. We have included an automatic updater in Yeoman to bump you when a new version ships, but if you need to do it manually: `npm update yeoman -g`
-
-
-# Uninstall
-
-You may want to uninstall the globally installed package by running the
-following command:
-
-```
-npm uninstall yeoman -g
-```
-
-So sad to see you go ☹
-
-You may need to do a more comprehensive uninstall if you're having problems; see [the troubleshooting guide](https://github.com/yeoman/yeoman/wiki/Additional-FAQ) in this case.
View
3  docs/readme.md
@@ -1,3 +0,0 @@
-# Documentation
-
-The markdown files for our documentation can be found in this directory. These are mirrored in the yeoman.io repository.

3 comments on commit c020b50

@jperl

Out of curiosity for my own project, why do you prefer the wiki over .md files? Is it because the project is becoming very large?

@sindresorhus

I usually don't, but it makes it easier for people to contribute to the docs, since GitHub wikis are open for anyone to edit. Also a lot quicker to do small changes in the web editor than having to pull, edit, commit, push. It's also easier to link pages together in the Wiki.

@jperl

Thanks for the insight. That makes a lot of sense for an open source project.

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