Yeoman Generator

This module is a Yeoman generator for doc-metrix Node.js modules.

Note: this generator is tailored for providing an API to JSON specifications. For other utilities, you will need to remove the boilerplate code in the library, text, and example files.

Getting Started

To use the generator, ensure that you have installed Yeoman:

$ npm install -g yo

For a general overview of Yeoman generators, see the Getting Started Guide.

Installation

$ npm install -g generator-doc-metrix-node

Usage

Once installed, navigate to the directory in which you want to place generated files and run

$ yo doc-metrix-node

The generator will provide a series of prompts and will use your answers to tailor the module files, providing a scaffold upon which you can immediately build.

Prompts

The prompts are as follows...

Module Name

The module name requires the convention that the module be prefixed with doc-metrix-. This ensures consistency with the current naming of doc-metrix Node.js modules.

Valid names include: doc-metrix-cpu, doc-metrix-memory, doc-metrix-network, etc. Do not include spaces or special characters in the name; e.g., doc metrix @ processes.

Also note that using the generator requires internet access, as module name availability is confirmed on NPM via npm-name.

Git

You have the option to initialize the module directory as a Git repository. The default option is Y. Typing enter or y+enter will confirm initialization and do the following:

$ git init
$ git remote add origin https://github.com/doc-metrix/<repo_name>.git
$ git add -A
$ git commit -m "[INIT]"

The initialization process stops short of pushing the commit to the remote repository.

Note: Git initialization assumes you have write access to the doc-metrix organization on Github. If you are not already a member and are interested in contributing, contact one of the owners.

Repository

If you elected to initialize a local Git repository, you must specify the corresponding remote repository name. The default is the unique module id (e.g., doc-metrix-cpu --> cpu ) with a -node suffix. Hence,

<name>-node

The -node suffix serves to distinguish the utility from similar utilities written in other languages.

Author

Enter the primary author's name; i.e., in all likelihood that will be your name.

Email

If you have chosen to initialize the directory as a Git repository, the default will be the email associated with your Github account. This email should be a correspondence address for those individuals wanting to contact you directly with their questions and comments.

If the Github email address is fine, just type enter.

License

Enter the license holder for this module. The default is your name, but this could be the organization for which you work (say, if they are helping sponsor development) or some other entity.

If the default option is fine, just type enter.

Description

Enter the module description.

Scaffold

Once you have answered all prompts, you will have the following scaffold:

examples/
	- index.js
lib/
	- index.js
scripts/
	- specs.js
test/
	- test.js
.gitignore
.npmignore
.travis.yml
LICENSE
Makefile
package.json
README.md
TODO.md

Dotfiles

These are standard fare. If you notice that files are neither tracking in Git nor making their way onto NPM, consult .gitignore and .npmignore. The scaffold includes a .travis.yml file for continuous integration purposes. Visit Travis-CI to setup running builds.

Makefile

The Makefile includes methods to run tests and generate notes. To see TODOs and FIXMEs,

$ make notes

License

The default license is the MIT license.

Package.json

The generator creates a scaffold package.json. You need to manually add keywords and any additional dependencies.

Documentation

The generator includes a TODO.md file. Use this file for general TODOs which are not tied to any particular file line.

The README.md is a scaffold. You should add to the usage and example code sections.

Scripts

The generator creates a post-install script for retrieving metric specifications: scripts/specs.js. If your module requires specifications, you should add to the resources object using the following convention:

var resources = {
		'spec_name': 'http://path/to/raw/specification.json',
		'spec_name': 'http://path/to/raw/specification.json',
		...
	};

The key should be the specification name as referred to in your module and the value is the absolute URL from which to retrieve the specification.

When a user downloads your module, the post-install script will fetch the remote resources and store them in a specs folder in the top-level application directory.

Lib

The main library file lib/index.js includes a skeleton module.

Test

The generator creates a skeleton test file. Aim for 100% test coverage.

Examples

The examples/index.js file should be modified to showcase the module's functionality and should match the example provided in the README.

Node Modules

The generator will automatically run npm install and install any node modules used by the scaffold. If you need any additional dependencies,

$ npm install <module_name> --save

or development dependencies (either for testing or examples)

$ npm install <module_name> --save-dev

Notes

If you opted to initialize the module as a Git repository, you will need to manually push changes to Github.

$ git push origin master

By default, the generator generates a Travis-CI *.yml file for continuous integration and uses Coveralls for tracking code coverage over time.

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ open reports/coverage/lcov-report/index.html

License

MIT license.

Copyright

Copyright © 2014. NodePrime.