Merge lp:~javier.collado/doit/bug425811 into lp:doit

[Javier Collado]

[Javier Collado (javier.collado)]

This branch provides a way to print some documentation when displaying the task list in a dodo file using the 'list' subcommand. To display the documentation the '-v', '--verbose' option must be passed. Otherwise, the same option as in the past will be passed.

The task documentation is extracted from:
- 'doc' key in the task dictionary
- Documentation string in task generator if available

[lp:~javier.collado/doit/bug425811]

129. By Javier Collado on 2009-09-07

verbose parameter is now options to avoid breaking test cases

[schettino72 (schettino72)]

I like the idea :)

* the verbose option should be true by default. so the 'list' should have an option to turn off verbose mode. (the default for the function main.py:doit_list doesn't matter)

* the docstring of the task doesnt work if the task yields sub-tasks.

* please dont put space around "=" for function parameters:
use => def doit_list(task_list, printSubtasks, verbose=False)
instead of => def doit_list(task_list, printSubtasks, verbose = False)

* I think we should get rid of those print statements
print "===== Tasks ====="
print "================="

* you use a ":" right after the task name. please include some space after the task name.

* I would prefer that the printed doc for a task to be limited by a single line. and the task doc be printed in the same line. if you want more lines you can keep it. or maybe create different verbosity levels.

* please write tests

review: Needs Fixing

[Javier Collado (javier.collado)]

Thanks for your comments. I'll go through them and let you know when code is ready for a new review.

[lp:~javier.collado/doit/bug425811]

130. By Javier Collado on 2009-09-15

Verbose option changed to quiet so printing the task documentation now is the default

131. By Javier Collado on 2009-09-15

Parenthesis removed for default values

132. By Javier Collado on 2009-09-15

Print statements for headers removed

133. By Javier Collado on 2009-09-15

Space added between task name and colon mark

134. By Javier Collado on 2009-09-15

Only first non-empty documentation line is printed

135. By Javier Collado on 2009-09-15

Updating old tests

136. By Javier Collado on 2009-09-15

Test cases that check documentation strings output added

137. By Javier Collado on 2009-09-15

Quiet test cases added to verify that documentation isn't printed in quiet mode

138. By Javier Collado on 2009-09-15

Merge from trunk

[Javier Collado (javier.collado)]

Latest branch revision should cover everything except for:

* the docstring of the task doesnt work if the task yields sub-tasks.

I'd say that the doc string from the generator shouldn't be used in the sub-tasks to avoid having multiple tasks with the same documentation string (which isn't very useful). Were you thinking about another solution?

[schettino72 (schettino72)]

> * the docstring of the task doesnt work if the task yields sub-tasks.
>
> I'd say that the doc string from the generator shouldn't be used in the sub-tasks to avoid having multiple tasks with the same documentation string (which isn't very useful). Were you thinking about another solution?

I have not looked at the branch yet... but what i mean is:

FILES = [file1, ...]
def task_pyflakes():
     """doc for group. execute pyflakes on all files"""
     for f in FILES:
         yield {'actions': ["pyflakes %s " % f],
                 'doc': "doc for sub-task"}

you should get the docstring as documentation for "pyflakes" top task
but not for each sub-task.

$ doit list

pyflakes : doc for group. execute pyflakes on all files

$ doit list --all

pyflakes : doc for group. execute pyflakes on all files
pyflakes:file1 : doc for sub-task
....

[Javier Collado (javier.collado)]

Ok, we have the same understanding about how should it work. Let me write a few test cases to verify that (I've just realized that pyflakes in your example gets no documentation at all) and I'll ask for another review.

[lp:~javier.collado/doit/bug425811]

139. By Javier Collado on 2009-09-18

Added test to make sure that documentation strings are correctly generated either from doc dictionary key or from generator documentation string
Documentation string not being used for generators fixed.

[Javier Collado (javier.collado)]

Test case added and problem fixed in rev 139. Ready for a new review round.

[schettino72 (schettino72)]

merged on 131.

there was a bug handling docstrings containing only empty lines.

I am not very happy with the output formating... it is hard to read. I guess 2 columns would look better.

review: Approve

=== modified file 'bin/doit'
--- bin/doit	2009-09-06 05:01:33 +0000
+++ bin/doit	2009-09-07 16:57:25 +0000
@@ -131,12 +131,19 @@
                'help': "list include all sub-tasks from dodo file"
                }
 
+opt_list_verbose = {'name': 'verbose',
+                    'short': 'v',
+                    'long': 'verbose',
+                    'type': bool,
+                    'default': False,
+                    'help': 'print tasks documentation'}
+
 # TODO list should support "args" as a filter.
 def cmd_list(params, args):
     dodo_module = main.get_module(params['dodoFile'])
     command_names = params['sub'].keys()
     dodo_tasks = main.load_task_generators(dodo_module, command_names)
-    return main.doit_list(dodo_tasks['task_list'], params['all'])
+    return main.doit_list(dodo_tasks['task_list'], params['all'], params['verbose'])
 
 
 ##########################################################
@@ -304,7 +311,7 @@
     subCmd['run'] = cmdparse.Command('run', run_options, cmd_run, run_doc)
 
     # list command
-    list_options = (opt_dodo, opt_listall)
+    list_options = (opt_dodo, opt_listall, opt_list_verbose)
     subCmd['list'] = cmdparse.Command('list', list_options, cmd_list, list_doc)
 
     # forget command

=== modified file 'lib/doit/main.py'
--- lib/doit/main.py	2009-09-06 05:01:33 +0000
+++ lib/doit/main.py	2009-09-07 16:57:25 +0000
@@ -2,6 +2,7 @@
 import os
 import sys
 import inspect
+import itertools
 
 from doit.util import isgenerator
 from doit.task import InvalidTask, Task, dict_to_task
@@ -79,7 +80,7 @@
     # generate all tasks
     task_list = []
     for name, ref, line in funcs:
-        task_list.extend(generate_tasks(name, ref()))
+        task_list.extend(generate_tasks(name, ref(), ref.__doc__))
 
     # get default tasks
     default_tasks = getattr(dodo_module, 'DEFAULT_TASKS', None)
@@ -91,7 +92,7 @@
     return {'task_list': task_list,
             'default_tasks': default_tasks}
 
-def generate_tasks(name, gen_result):
+def generate_tasks(name, gen_result, gen_doc = None):
     """Create tasks from a task generator result.
 
     @param name: (string) name of taskgen function
@@ -104,6 +105,12 @@
             raise InvalidTask("Task %s. Only subtasks use field name."%name)
 
         gen_result['name'] = name
+
+        # Use task generator documentation
+        # if no documentation present in task list
+        if not 'doc' in gen_result:
+            gen_result['doc'] = gen_doc
+
         return [dict_to_task(gen_result)]
 
     # a generator
@@ -280,7 +287,7 @@
 
 
 
-def doit_list(task_list, printSubtasks):
+def doit_list(task_list, printSubtasks, verbose):
     """List task generators, in the order they were defined.
 
     @param printSubtasks: (bool) print subtasks
@@ -288,7 +295,14 @@
     print "==== Tasks ===="
     for task in task_list:
         if (not task.is_subtask) or printSubtasks:
-            print task.name
+            task_str = task.name
+            if verbose and task.doc:
+                doc_lines = [line.strip()
+                             for line in task.doc.splitlines()]
+                doc_lines = list(itertools.dropwhile(lambda line: not line, reversed(doc_lines)))
+                doc_lines = list(itertools.dropwhile(lambda line: not line, reversed(doc_lines)))
+                task_str += ":\n%s\n" % "\n".join(["\t%s" % line for line in doc_lines])
+            print task_str
     print "="*25,"\n"
     return 0
 

=== modified file 'lib/doit/task.py'
--- lib/doit/task.py	2009-09-06 05:01:33 +0000
+++ lib/doit/task.py	2009-09-07 16:57:25 +0000
@@ -228,10 +228,11 @@
     @ivar file_dep: (list - string)
     @ivar run_once: (bool) task without dependencies should run
     @ivar is_subtask: (bool) indicate this task is a subtask.
+    @ivar doc: (string) task documentation
     """
 
     def __init__(self,name, actions, dependencies=(),targets=(),setup=None,
-                 is_subtask=False):
+                 is_subtask=False, doc=None):
         """Init."""
         # dependencies parameter must be a list
         if not ((isinstance(dependencies,list)) or
@@ -263,6 +264,7 @@
         self.setup = setup
         self.run_once = False
         self.is_subtask = is_subtask
+        self.doc = doc
 
         # there are 3 kinds of dependencies: file, task, and folder
         self.folder_dep = []
@@ -334,7 +336,7 @@
     @raise InvalidTask: If unexpected fields were passed in task_dict
     """
     # TASK_ATTRS: sequence of know attributes(keys) of a task dict.
-    TASK_ATTRS = ('name','actions','dependencies','targets','setup')
+    TASK_ATTRS = ('name','actions','dependencies','targets','setup', 'doc')
     # FIXME check field 'name'
 
     # === DREPREACATED on 0.4 (to be removed on 0.5): START
@@ -358,9 +360,4 @@
             raise InvalidTask("Task %s contain invalid field: %s"%
                               (task_dict['name'],key))
 
-    return Task(task_dict.get('name'),
-                task_dict.get('actions'),
-                task_dict.get('dependencies',[]),
-                task_dict.get('targets',[]),
-                task_dict.get('setup',None),
-                )
+    return Task(**task_dict)