Create a Fabsetup Addon¶

In a Nutshell¶

Scaffold: Run fabsetup new which scaffolds a new Fabsetup addon
Code: Implement Your task, use decorators task, subtask, and subsubtask of module fabsetup.fabutils.task
Documentation: Set up documentation (sphinx powered page)
CI/CD: Auto-test Your addon and set up shields
PyPI: Publish Your addon repository on git{hub,lab,…} and upload Your addon to PyPI

En Détail¶

Scaffold¶

fabsetup new

Code¶

Implement Your task, use decorators of module fabsetup.fabutils.task.

An academic example:

from fabsetup.fabutils.task import task, subtask, subsubtask

@subsubtask
def my_subsubtask_a(c):
    '''subsubtask a'''
    c.run('echo subsubtask a')


@subsubtask
def my_subsubtask_b(c):
    '''subsubtask b'''
    c.run('echo subsubtask b')


@subtask
def my_subtask_1(c):
    '''subtask 1'''
    c.run('echo subtask 1')
    my_subsubtask_a(c)
    my_subsubtask_b(c)


@subsubtask
def my_subsubtask_c(c):
    '''subsubtask c'''
    c.run('echo subsubtask c')


@subsubtask
def my_subsubtask_d(c):
    '''subsubtask d'''
    c.run('echo subsubtask d')


@subtask
def my_subtask_2(c):
    '''subtask 2'''
    c.run('echo subtask 2')
    my_subsubtask_c(c)
    my_subsubtask_d(c)


@task
def my_task(c):
    '''Run my_subtask_1 and my_subtask_2'''
    c.run('echo task')
    my_subtask_1(c)
    my_subtask_2(c)

Documentation¶

set up documentation (github page)

CI/CD¶

TODO: auto-test Your addon and use shields

PyPI¶

upload to pypi

More Details¶

Files¶

Where to put files and templates, used by a fabsetup task.

Git Repositories¶

How to manage a git repository used by a fabsetup task.

Downloads¶

How to manage a downloaded file used by a fabsetup task.

Styleguide¶

“I whish You all the best four Your Fabsetup addon.”

Cleanliness¶

There is PEP 8. And tools like flake8 and black. Please meet this baseline in writing clean code.

Comprehensibility¶

A Fabsetup user should understand for every single command of a task why it is executed. Therefore, please write a docstring for every task, subtask, and subsubtask and describe what the code is intended to achieve.

Traceability¶

A Fabsetup user should be able to achieve what a task does by manually executing each command listed on task execution. Therefore, please use “all-inclusive” commands (e.g. cd path/to/somewhere && ./run-something instead of invoke.context.Context.cd which would not show the current dir where a command is executed from). Also, consider to avoide the execution of hidden commands in Your task.

Repetitions¶

By intuition, a Fabsetup user expects that repeated runs of a Fabsetup task would not alter the achievements of the first run. Please take care to meet this assumption of idempotency for Your task.

Markdown Output¶

You probably have noted that the output of the tasks info and new is in markdown. Please assure that Your fabsetup addon also creates markdown formatted output.