ploomber Documenting tasks via docstrings

Documenting tasks via docstrings

Open idomic opened this issue 2 years ago • 4 comments

We have a feature that isn't documented, from a user:

Hi, how do I define the documentation for a particular task in the pipeline? When I run ploomber status, I see the column Doc(short) which is always empty. A follow-up question is can I customize the status report ?

the documentation is extracted from the docstrings (if your function is a task); alternatively, if your task is a script or a notebook, you can define a string at the top of a markdown cell. example:

documentation for my script/notebook

In case of functions that look like the following:

def func1():
    ...
def func2():
    ...
if __name__ == "__main__":
    func1()
    func2()

This is how you add the docstring:

def func():
    """some comment"""
    ...

if you want to customize the output of ploomber status you can use the Python API, you can load your pipeline with this, then call dag.status() and then you can manipulate the object. here's the Table object that it'll return: https://github.com/ploomber/ploomber/blob/2a6287f1beea9f51ecbe59ddebac266cef6c77e8/src/ploomber/table.py#L69

We should document this functionality.