From e839b093a01d9e2059ccfe997801433722af2b33 Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Mon, 10 Aug 2015 10:29:35 -0700 Subject: move compilting to build-tools, rewrite some grunt stuff, add local docs with jekyll section based on readme's more detailed walkthrough --- docs/getting-started/build-tools.md | 64 +++++++++++++++++++++++++++++++++++++ docs/getting-started/compiling.md | 57 --------------------------------- 2 files changed, 64 insertions(+), 57 deletions(-) create mode 100644 docs/getting-started/build-tools.md delete mode 100644 docs/getting-started/compiling.md (limited to 'docs/getting-started') diff --git a/docs/getting-started/build-tools.md b/docs/getting-started/build-tools.md new file mode 100644 index 000000000..9d91dbe11 --- /dev/null +++ b/docs/getting-started/build-tools.md @@ -0,0 +1,64 @@ +--- +layout: page +title: Build tools +group: getting-started +--- + +Bootstrap uses [Grunt](http://gruntjs.com) for its CSS and JavaScript build system and Jekyll for the written documentation. Our Gruntfile includes convenient methods for working with the framework, including compiling code, running tests, and more. + +## Tooling setup + +To use our Gruntfile and run our documentation locally, you'll need a copy of Bootstrap's source files, Node, and Grunt. Follow these steps and you should be ready to rock: + +1. [Download and install Node](https://nodejs.org/download), which we use to manage our dependencies. +2. Install the Grunt command line tools, `grunt-cli`, with `npm install -g grunt-cli`. +3. Navigate to the root `/bootstrap` directory and run `npm install` to install our local dependencies listed in [package.json](https://github.com/twbs/bootstrap/blob/master/package.json). +4. [Install Ruby][install-ruby], install [Bundler][gembundler] with `gem install bundler`, and finally run `bundle`. This will install all Ruby dependencies, such as Jekyll and Sass linter. + +When completed, you'll be able to run the various Grunt commands provided from the command line. + +**Unfamiliar with npm? Don't have node installed?** That's a-okay. npm stands for [node packaged modules](http://npmjs.com/) and is a way to manage development dependencies through node.js. [Download and install node.js](https://nodejs.org/download/) before proceeding. + +[install-ruby]: https://www.ruby-lang.org/en/documentation/installation/ +[gembundler]: http://bundler.io/ + +## Using Grunt + +Our Gruntfile includes the following commands and tasks: + +| Task | Description | +| --- | --- | +| `grunt` | Run `grunt` to run tests locally and compile the CSS and JavaScript into `/dist`. **Uses [Sass](http://sass-lang.com/) and [UglifyJS](http://lisperator.net/uglifyjs/).** | +| `grunt dist` | `grunt dist` creates the `/dist` directory with compiled files. **Uses [Sass](http://sass-lang.com/) and [UglifyJS](http://lisperator.net/uglifyjs/).** | +| `grunt test` | Runs [JSHint](http://jshint.com) and [QUnit](http://qunitjs.com/) tests headlessly in [PhantomJS](http://phantomjs.org/) (used for CI). | +| `grunt docs` | Builds and tests CSS, JavaScript, and other assets which are used when running the documentation locally via `jekyll serve`. | +| `grunt watch` | This is a convenience method for watching just Sass files and automatically building them whenever you save. | + +## Switching Sass compilers + +Bootstrap will be compiled with [libsass][libsass] by default, but you can opt into traditional Ruby Sass by setting the `TWBS_SASS` environment variable. Two options are supported: + +* `libsass` (default) to use [libsass][libsass] via [grunt-sass][grunt-sass]. +* `sass` to use [Ruby Sass][ruby-sass] via [grunt-contrib-sass][grunt-contrib-sass]. + +For example, run `TWBS_SASS=sass grunt` to test and build Bootstrap with Ruby Sass. + +[ruby-sass]: https://github.com/sass/sass +[grunt-contrib-sass]: https://github.com/gruntjs/grunt-contrib-sass +[libsass]: https://github.com/sass/libsass +[grunt-sass]: https://github.com/sindresorhus/grunt-sass + +## Local documentation + +Running our documentation locally requires the use of Jekyll, a decently flexible static site generator that provides us basic includes, Markdown-based files, templates, and more. Here's how to get it started: + +1. Run through the [tooling setup](#tooling-setup) above to install Jekyll (the site builder) and Rouge (our syntax highlighter). + - **Windows users:** Read [this unofficial guide](http://jekyll-windows.juthilo.com/) to get Jekyll up and running without problems. +2. From the root `/bootstrap` directory, run `jekyll serve` in the command line. +3. Open in your browser, and voilà. + +Learn more about using Jekyll by reading its [documentation](http://jekyllrb.com/docs/home/). + +## Troubleshooting + +Should you encounter problems with installing dependencies or running Grunt commands, uninstall all previous dependency versions (global and local). Then, rerun `npm install`. diff --git a/docs/getting-started/compiling.md b/docs/getting-started/compiling.md deleted file mode 100644 index 46c3b0f2d..000000000 --- a/docs/getting-started/compiling.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: page -title: Compiling -group: getting-started ---- - -Bootstrap uses [Grunt](http://gruntjs.com) for its build system, with convenient methods for working with the framework. It's how we compile our code, run tests, and more. - -## Contents - -* Will be replaced with the ToC, excluding the "Contents" header -{:toc} - -## Install Grunt - -**To install Grunt, you must first [download and install node.js](https://nodejs.org/download/)** (which includes npm). npm stands for [node packaged modules](http://npmjs.com/) and is a way to manage development dependencies through node.js. - -From the command line: - -1. Install `grunt-cli` globally with `npm install -g grunt-cli`. -2. Navigate to the root `/bootstrap` directory, then run `npm install`. npm will look at [package.json](https://github.com/twbs/bootstrap/blob/master/package.json) and automatically install the necessary local dependencies listed there. -3. [Install Ruby][install-ruby], install [Bundler][gembundler] with `gem install bundler`, and finally run `bundle`. This will install all Ruby dependencies, such as Jekyll and Sass linter. - -When completed, you'll be able to run the various Grunt commands provided from the command line. - -**Unfamiliar with npm? Don't have node installed?** That's a-okay. npm stands for [node packaged modules](http://npmjs.com/) and is a way to manage development dependencies through node.js. [Download and install node.js](https://nodejs.org/download/) before proceeding. - -[install-ruby]: https://www.ruby-lang.org/en/documentation/installation/ -[gembundler]: http://bundler.io/ - -## Available Grunt commands - -| Task | Description | -| --- | --- | -| `grunt` | Run `grunt` to run tests locally and compile the CSS and JavaScript into `/dist`. **Uses [Sass](http://sass-lang.com/) and [UglifyJS](http://lisperator.net/uglifyjs/).** | -| `grunt dist` | `grunt dist` creates the `/dist` directory with compiled files. **Uses [Sass](http://sass-lang.com/) and [UglifyJS](http://lisperator.net/uglifyjs/).** | -| `grunt test` | Runs [JSHint](http://jshint.com) and [QUnit](http://qunitjs.com/) tests headlessly in [PhantomJS](http://phantomjs.org/) (used for CI). | -| `grunt docs` | Builds and tests CSS, JavaScript, and other assets which are used when running the documentation locally via `jekyll serve`. | -| `grunt watch` | This is a convenience method for watching just Sass files and automatically building them whenever you save. | - -## Use another Sass compiler - -Bootstrap is compiled with [libsass][libsass] by default. Use another compiler by setting the `TWBS_SASS` environment variable to: - -* `sass` to use [Ruby Sass][ruby-sass] via [grunt-contrib-sass][grunt-contrib-sass]. -* `libsass` (default) to use [libsass][libsass] via [grunt-sass][grunt-sass]. - -For example, run `TWBS_SASS=sass grunt` to test and build Bootstrap with Ruby Sass. - -[ruby-sass]: https://github.com/sass/sass -[grunt-contrib-sass]: https://github.com/gruntjs/grunt-contrib-sass -[libsass]: https://github.com/sass/libsass -[grunt-sass]: https://github.com/sindresorhus/grunt-sass - -## Troubleshooting dependencies - -Should you encounter problems with installing dependencies or running Grunt commands, uninstall all previous dependency versions (global and local). Then, rerun `npm install`. -- cgit v1.2.3