Grunt tasks' discovery, help and information.

[dnutels]

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):

   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):

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:

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.

[wilmoore]

This is interesting and we actually do something similar on my team, except we delegate most of it to two helpers:

• require-grunt-configs
• load-grunt-tasks

Here is an gist of what this results in (very small top-level Gruntfile): https://gist.github.com/wilmoore/7425573#file-gruntfile-smaller-coffee

I think your other concern (task descriptions) is likely a separate discussion; but an interesting one that I'd like to see discussed. Would love to hear from @cowboy on that one.

[martinheidegger]

I have been asked at the last node-js meeting in tokyo for the documentation feature so: :+1:

btw.: I am in favour of documenting using an additional property:

grunt.registerTask(name, description, method, example-config);

[chrisl8888]

I'd like to see the second part: Listing all the tasks and then seeing what that task does. That seems simple enough. Is there existing work on this?

+1 for grunt --list or grunt -l

[dnutels]

I think the time has come for me to inquire on the progress in this direction.

Is there any :)?

[chrisl8888]

@dnutels http://stackoverflow.com/questions/15004624/list-grunt-js-tasks

[Enet4]

I would like to bump this issue, because not having an easy and simple way to programmatically retrieve a list of the project's grunt tasks (and only the grunt tasks) is a greater barrier than one might think. Since task descriptions are wrapped into new lines when they are too long, taking the first word of each line is not even enough. In vscode, grunt task detection was faulty because of that, and the latest solution still feels a bit too tricky. How about supporting JSON output of the tasks (--json) as well?