Grunt tasks' discovery, help and information.
- Dominant language
- JavaScript
- Stars
- 12.2k
- Forks
- 1.5k
- PR merge metrics
- No merged PRs in 30d
Description
I wasn't entirely sure where to file this, as this is not an issue, aside from, _may be_, usability concern.
Basically, on a team of multiple developers, using Grunt is easy if you know all the tasks (which in many cases are quite complex and not just default ones), but quite problematic otherwise.
The process of finding and using an unfamiliar task contains several steps:
1. Go through `Gruntfile` or execute `grunt --help` for _initial_ discovery
2. Go through documentation for the task in the `Gruntfile`
and when a task is a bit more familiar, but still not absolutely memorized (which may be never for some folks) - _basically the same process again_. There is no shortcut.
There is also an additional complication - my team uses Grunt in a way I haven't seen yet (so, at the very least, it's not a common one), but which, to us, seems very convenient:
1. We separate all tasks (including `grunt-*` and `grunt-contrib-*` ones) into separate files in the same folder and load them all with:
`grunt.loadTasks(grunt.config.process('<%= tasksDir %>'));`
2. Each individual task does the following (here on `grunt-contrib-yuidoc` example):
``` javascript
module.exports = function (grunt) {
grunt.loadNpmTasks('grunt-contrib-yuidoc');
grunt.config('yuidoc',
{
options: {
...
}
...
}
);
};
```
My suggestion is to do a relatively simple, code wise, extension that would allow an additional, optional parameter to `grunt.config.set`/`grunt.config`, `grunt.registerTask` and `grunt.config.init` (a bit differently from the below, naturally):
``` javascript
grunt.config('yuidoc',
{
options: {
...
}
...
},
description: 'some static and unformatted description text'
);
```
or, to allow more of a control over the output's formatting and/or dynamic creation:
``` javascript
grunt.config('yuidoc',
{
options: {
...
}
...
},
description: function(grunt) {
...
}
);
```
or alternatively create a new standard `description` property (similar to `options`) that would serve the same purpose and then allow discovery of the tasks with something similar to:
`grunt --list` or `grunt -l`
to output full list of tasks with their descriptions (as provided by `description` configuration parameter) and, when narrowing down:
`grunt --list:yuidoc`
to keep up with the common flags style of Grunt tasks, where flag may be even partial as in `grunt --list:yui` and all matching tasks would then be shown.
I realize that I can, of course, write such a task by myself, but then I would have to infer what on `grunt.config` is a task and what is some custom property and all around hack it, so to speak.
How do you guys feel about such a thing?
P.S. responses of **use X instead** are welcome and anticipated, to save us all work.
Contributor guide
Assessment
This issue has not been assessed yet.