Generator-graphic NPM

generator-graphic

A generator for Yeoman, built for data journalists. This branch is specific to the Washington Post -- see the generic branch for a more-readily forkable version.

Why?

Accuracy

A smart generator encourages using proper data integrity protection techniques.

Keep original data files separated
Use make to keep data manipulations documented
Include README.md for proper documentation

Speed

Using a generator speeds up repetitive tasks we don't have the time (or patience) to keep performing.

Easily include popular JavaScript dependencies
Uses grunt commands for frequent tasks, like starting a server or converting preprocessed css.

Deployment

Keep ready-to-deploy project in public folder
Extend with scripts for deployment in your environment

Installation

generator-graphic is available on npm:

npm install -g generator-graphic

Usage

In a terminal, create a directory for your graphic to live in, and cd into it. For example:

# Move into the parent directory of your graphic
cd ~/wapo/wapo-static/business/

# Create a new directory for this graphic
mkdir reimagining-union-station

# Move into this newly created directory
cd reimagining-union-station

Then, start the generator:

yo graphic

Follow the prompts:

[?] What is the slug? reimagining-union-station
[?] Would you like to use a prebuilt template? No
[?] Which libraries would you like to include? (Press <space> to select)
>o d3
 o underscore
...

To view the graphic locally:

grunt

Bower

generator-graphic uses bower to manage dependencies. To add a dependency to the project:

# Install the package
bower install <package> --save

# Rebuild the project (creates `public/lib/all-min.js`)
grunt build

The bower docs have more information on what can be used as <package> in the above example.

Compass/SASS

generator-graphic optionally includes Compass/SASS. To compile .scss files automatically:

grunt compass

This requires Compass to be installed on your machine. If it isn't already, follow these instructions.

"Installing" someone else's graphic

generator-graphic installs everything when you create a graphic, but if you're jumping into someone else's graphic, you have to do this yourself. Don't fret -- it's easy:

# Installs node packages, like grunt, based on `package.json`.
npm install

# Installs required javascript libraries, like underscore, based
# on `bower.json`.
bower install

Directory structure

generator-graphic sets up the following directory structure:

project-folder
|
|-- .gitignore
|
|-- Gruntfile.js        defines grunt commands, like `grunt server`
|
|-- Makefile            encourage automation of data manipulations
|
|-- README.md           project documentation
|
|-- bower.json          defines project dependencies
|
|-- bower_components    location of installed project dependencies
|
|-- build               directory for temporary build files
|
|-- data                data files
|
|-- node_modules        node dependency files, autogenerated
|
|-- metadata.yaml       graphic headline, blurb, byline, etc.
|
|-- package.json        defines project settings
|
|-- project-files       illustrator files, others to be ignored by git
|
|-- public              folder to be deployed to web server
|   |-- index.html
|   |-- css
|   |   `-- base.css
|   |
|   |-- js
|   |   `-- base.js
|   |
|   `-- lib
|       `-- all.js      build automatically through grunt and bower
|
`-- sass                optionally included for compass/sass files
    `-- base.scss