Using Fabric==1.8.3
:
Your code with added imports and managing docstring for tasks: fabfile.py:
from fabric.api import *
from fabric.tasks import Task
class BaseConfig(Task):
"""BaseConfig task docstring"""
def run(self):
"""BaseConfig task docstring for `run` method"""
env.env = self.name
env.user = 'serafeim'
env.role = self.name
puts("Using {0} configuration with user {1} at {2}".format(env.env, env.user, env.roledefs[env.env]))
class UatConfig(BaseConfig):
"""
UAT settings
"""
name = "uat"
uat_cfg_instance = UatConfig()
class ProdConfig(BaseConfig):
"""
Prod settings
talking a bit more about our classy concept, not yet diving into `run` details
"""
name = "prod"
def run(self):
"""ProdConfig run docstring
on multiple lines
we are now in prod"""
super(ProdConfig, self).run()
prod_cfg_instance = ProdConfig()
Listing available tasks
$ fab -l
Available commands:
prod Prod settings
uat UAT settings
Here we see, that docstring from class derived from Task is used - but just the first line.
Show detailed docstring for uat - docstring from super class
Detailed description for uat
illustrates the problem you have described:
$ fab -d uat
Displaying detailed information for task 'uat':
BaseConfig task docstring for `run` method
Arguments: self
As uat
does not redefine run
method, parent run
method is used and this applies to presenting docstring for task details.
Show detailed docstring for prod - docstring from run
method
For prod
we redefine run
method and this gives us us a chance to modify docstring for the task:
$ fab -d prod
Displaying detailed information for task 'prod':
ProdConfig run docstring
on multiple lines
we are now in prod
Arguments: self
Conclusions
- brief listing (via
$ fab -l
) shows first line of class docstring - detailed listing (via
$ fab -d <taskname>
) shows docstring from usedrun
method - if you want to change task detailed docstring, you have to define
run
method in your inherited class and specify the docstring there. Do not forget to callrun
from super class (if it is relevant).