Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 180 lines (114 sloc) 6.581 kb
fe3d0b9 @paulirish readme updates
paulirish authored
1 # Welcome, Friend!
2
325ebaa @addyosmani Some more readme tweaks.
addyosmani authored
3 ## What am I?
4
5 Yeoman is a robust and opinionated client-side stack, comprised of tools and frameworks that can help developers quickly build beautiful web applications. We take care of providing everything needed to get started without any of the normal headaches associated with a manual setup.
6
7 Yeoman is fast, performant and is optimized to work best in modern browsers.
8
d063611 @sindresorhus Improve readme
sindresorhus authored
9 For more information about the project, see [yeoman.io](http://yeoman.io).
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
10
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
11
f565bca @addyosmani Updating references to docs, tweaking.
addyosmani authored
12 ## Installing (pre-launch)
fe3d0b9 @paulirish readme updates
paulirish authored
13
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
14 * Clone this repo and `cd` into it
d063611 @sindresorhus Improve readme
sindresorhus authored
15 * Run this command: `./setup/install.sh`
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
16 * Navigate to a new directory and run `yeoman init` to make sure everything is working as expected.
450e42c @paulirish adding rvm to install dependencies. cleanup of readme. Install is eas…
paulirish authored
17
fe3d0b9 @paulirish readme updates
paulirish authored
18
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
19 ## Documentation
20
21 Yeoman supports a powerful set of high-level commands. These include:
22
8f98e17 @paulirish more syntax highlighting
paulirish authored
23 ```shell
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
24 yeoman init # Initialize and scaffold a new project using generator templates
25 yeoman build # Build an optimized version of your app, ready to deploy
26 yeoman server # Launch a preview server which will begin watching for changes
c269e4c @paulmillr Update refs to mocha.
paulmillr authored
27 yeoman test # Run a Mocha test harness in a headless Phantom.js
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
28
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
29 yeoman install # Install a package from the client-side package registry
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
30 yeoman uninstall # Uninstall the package
31 yeoman update # Update a package to the latest version
32 yeoman list # List the packages currently installed
33 yeoman search # Query the registry for matching package names
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
34 yeoman lookup # Look up info on a particular package
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
35
36 ```
37
38 A common initial workflow with Yeoman might be:
39
8f98e17 @paulirish more syntax highlighting
paulirish authored
40 ```shell
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
41 yeoman init # Invoke the most basic application scaffold (Bootstrap, Boilerplate etc.)
42 yeoman build # Build your project, creating an optimized version in the publish folder
43 yeoman server # Create an intermediate version of your app, firing off a watch process
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
44
45 ```
46
47 Some more examples of how to use our commands include:
48
8f98e17 @paulirish more syntax highlighting
paulirish authored
49 ```shell
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
50 yeoman init angular:bootstrap # Invoke the AngularJS generator scaffold
51 yeoman init angular:controller # Invoke the AngularJS Controller sub-generator
52 yeoman install jquery underscore [depName] # Install a dependency or dependencies
53 yeoman update jquery # Update a specific dependency (e.g jquery)
54 yeoman search jquery # Lookup jquery in the Bower registry
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
55 ```
56
57
f565bca @addyosmani Updating references to docs, tweaking.
addyosmani authored
58 See the [complete documentation](https://github.com/yeoman/yeoman/tree/master/docs/cli) for more. We also have [extended documentation](https://github.com/mklabs/yeoman/wiki/_pages) available for those more interested in the Yeoman internals.
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
59
60
61
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
62 ### Trouble-shooting
63
64 If for any reason you experience exceptions after the yeoman installation process above, you may find the
65 following steps resolve these issues:
66
8f98e17 @paulirish more syntax highlighting
paulirish authored
67 ```shell
68 cd yeoman/cli
69 sudo -s 'npm install -g && npm link'
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
70 ```
fe3d0b9 @paulirish readme updates
paulirish authored
71
eb655aa @addyosmani Adding note about bower access.
addyosmani authored
72 Please also note that (pre-launch) commands such as `yeoman install`, `yeoman update` and `yeoman search` etc (i.e package management commands) will only work if you have Bower installed. As this is currently in private beta, please let us know if you need access and we'll sort that out.
73
f565bca @addyosmani Updating references to docs, tweaking.
addyosmani authored
74 Should you run into any further problems beyond this, please open a [new issue](https://github.com/yeoman/yeoman/issues/new) and one of the team will be happy to follow up with you.
75
450e42c @paulirish adding rvm to install dependencies. cleanup of readme. Install is eas…
paulirish authored
76 ## Running
fe3d0b9 @paulirish readme updates
paulirish authored
77
d063611 @sindresorhus Improve readme
sindresorhus authored
78 Here's a small shell script that you can save as `server.sh` which opens and serves the current directory:
79
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
80 ```shell
d063611 @sindresorhus Improve readme
sindresorhus authored
81 #!/usr/bin/env sh
b9b8779 @ebidel Linux support
ebidel authored
82
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
83 port=$1
d063611 @sindresorhus Improve readme
sindresorhus authored
84 if [ $# -ne 1 ]; then
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
85 port=8000
86 fi
87
d063611 @sindresorhus Improve readme
sindresorhus authored
88 if [ $(uname -s) == "Darwin" ]; then
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
89 open=open
90 else
91 open=xdg-open
92 fi
93
94 $open http://localhost:$port && python -m SimpleHTTPServer $port;
b9b8779 @ebidel Linux support
ebidel authored
95 ```
96
d063611 @sindresorhus Improve readme
sindresorhus authored
97 You then need to make it executable: `$ chmod +x server.sh`
b9b8779 @ebidel Linux support
ebidel authored
98
d063611 @sindresorhus Improve readme
sindresorhus authored
99 For example, run this guy as `$ server` (defaults to port 8000), or supply a port yourself `$ server 3000`.
59c0d7f @addyosmani Adding browser support to README.
addyosmani authored
100
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
101
325ebaa @addyosmani Some more readme tweaks.
addyosmani authored
102
59c0d7f @addyosmani Adding browser support to README.
addyosmani authored
103 ## Browser Support
104
d063611 @sindresorhus Improve readme
sindresorhus authored
105 * Modern browsers (latest version of Chrome, Safari, Firefox, Opera and IE10)
59c0d7f @addyosmani Adding browser support to README.
addyosmani authored
106 * Chrome on Android
107 * Mobile Safari
108
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
109
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
110 ## Platform Support
111
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
112 Yeoman 1.0 will support OS X and will attempt to support Linux as well. We will be aiming to bring in support for Windows in a future version of the project.
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
113
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
114 ## Contribute
115
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
116 ### Repos
117
118 * [Yeoman (CLI, Insights)](http://github.com/yeoman/yeoman)
119 * [Yeoman I/O Holding Page](http://github.com/yeoman/yeoman.io)
d063611 @sindresorhus Improve readme
sindresorhus authored
120 * [Yeoman I/O Site](http://github.com/yeoman/yeoman.io) (site branch)
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
121
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
122 ### Style Guide
123
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
124 This project follows the [jQuery Style Guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines) with an exception of two space indentation and multiple var statements. Please ensure any pull requests follow this closely. If you notice existing code which doesn't follow these practices, feel free to shout and we will address this.
125
b9fe2e5 @sindresorhus Make the CLI code pass JSHint
sindresorhus authored
126 ### Pull Request Guidelines
127
128 - Lint the code by running `grunt` in the `/cli` folder before submitting a pull request
129 - Develop in a topic branch, not master
130
987517f @paulirish update readme with testing info.
paulirish authored
131 ### Tests
132
133 Yeoman has a test suite to ensure it's reliably and accurately working as a developer tool. You can find the main test suite in [`test/test-build.js`](https://github.com/yeoman/yeoman/blob/master/cli/test/test-build.js), most of the assertions are [checks against yeoman cli stdout](https://github.com/mklabs/yeoman/wiki/test-build).
134
b4b6057 @paulirish readme update about testing
paulirish authored
135 To run our test suite:
136
137 ```sh
138 npm test
139 ```
140
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
141 Do note that if any CLI prompts are not accounted for the test suite will have a timeout failure.
b4b6057 @paulirish readme update about testing
paulirish authored
142
d6c85b5 @paulirish add to readme about our existing developer documentation.
paulirish authored
143 ### Developer Docs
144
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
145 We have significant developer docs for you if you'd like to hack on Yeoman.
d6c85b5 @paulirish add to readme about our existing developer documentation.
paulirish authored
146
f565bca @addyosmani Updating references to docs, tweaking.
addyosmani authored
147 Currently you can find much of the details on [mklabs' yeoman wiki](https://github.com/mklabs/yeoman/wiki/_pages) but also [our first site's docs section](https://github.com/yeoman/yeoman/tree/master/docs/cli).
d6c85b5 @paulirish add to readme about our existing developer documentation.
paulirish authored
148
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
149 You're also welcome to `git blame` back to commit messages and pull requests. As a project we value comprehensive discussion for our fellow developers.
b9fe2e5 @sindresorhus Make the CLI code pass JSHint
sindresorhus authored
150
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
151 ## About
152
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
153 Yeoman is an open-source project by [Google](http://google.com) which builds on top of [Grunt](https://github.com/cowboy/grunt) and [node-build-script](http://github.com/h5bp/node-build-script). We utilize a number of useful open-source solutions including:
154
155 * Twitter Bootstrap
d063611 @sindresorhus Improve readme
sindresorhus authored
156 * HTML5 Boilerplate
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
157 * Modernizr
158 * Twitter Bower
d063611 @sindresorhus Improve readme
sindresorhus authored
159 * Node.js
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
160 * NPM
161 * Compass
d063611 @sindresorhus Improve readme
sindresorhus authored
162 * Socket.IO
163 * CoffeeScript
164 * Mocha
165 * Jasmine
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
166 * PhantomJS
d063611 @sindresorhus Improve readme
sindresorhus authored
167 * And [more...](https://github.com/yeoman/yeoman/wiki/Dependencies)
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
168
169 Version 1 of the project features the combined efforts of:
170
d063611 @sindresorhus Improve readme
sindresorhus authored
171 * [Paul Irish](http://paulirish.com)
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
172 * [Addy Osmani](http://addyosmani.com)
d063611 @sindresorhus Improve readme
sindresorhus authored
173 * [Mickael Daniel](http://blog.mklog.fr)
174 * [Sindre Sorhus](http://sindresorhus.com)
8bc0352 @ebidel Update master
ebidel authored
175 * [Eric Bidelman](http://ericbidelman.com)
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
176
d063611 @sindresorhus Improve readme
sindresorhus authored
177 and other developers.
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
178
f565bca @addyosmani Updating references to docs, tweaking.
addyosmani authored
179 We will be aiming to officially release the project in Q3, 2012.
Something went wrong with that request. Please try again.