What is the best practice of decorating tasks. I have modules where I decorated funcs with @task. Then I import them in main.py for the Flow. But I'm having problem using sphinx to generate docs. No error messages just HTML output does not contain doc strings

Your pattern seems perfectly valid; could you share the errors you’re seeing?

Actually there is no error message. Sphinx cannot find the docs strings I had in the original function. So I only see function names and parameters in my HTML ouyput

oooo I understand; your original function along with its docstring is available in the

run

method of the task. Two options: - directly reassign the docstring (

my_task.__doc__ = my_task.run.__doc__

) - have sphinx look at

my_task.run

when generating docs

Ahh thanks! Problem solved 👌🏾

💯

where should

my_task.__doc__ = my_task.run.__doc__

go? After the

@task

annotation or within the function or just anywhere in the file?

After the

@task

annotation

@task()
process_itemwise.__doc__ = process_itemwise.run.__doc__
def process_itemwise(data):
    """processes individual items

    Args:
       data: A dict of values
    """

    data["result"] = 1
    return data

I am not able to get this to work. If I use this, it does not execute. I get syntax error. I tried putting it inside the function and after the function as well. But no luck.

Oh sorry, I didn’t mean immediately after the annotation:

@task()
def process_itemwise(data):
    """processes individual items

    Args:
       data: A dict of values
    """

    data["result"] = 1
    return data

process_itemwise.__doc__ = process_itemwise.run.__doc__

Hi Chris, I don’t know why but it is not working for me.

"""Sample module to verify sphinx doc generation
"""

from prefect import task

@task()
def process_itemwise(data):
    """processes individual items

    Args:
       data: A dict of values
    """

    data["result"] = 1
    return data

process_itemwise.__doc__ = process_itemwise.run.__doc__

When I run

python setup.py docs

the html documentation only shows the module comment and the function itself does not appear. If I remove the @task annotation the function documentation appears. I had used pyscaffold to create the initial repo and then added this fle.

Hi @Jerry Thomas so to be honest I’m not super familiar with Sphinx, so I can’t speak to why it’s not documenting your function; the

__doc__

line just ensures that the docstring for your task agrees with the doc string that you wrote (and I might actually PR a change to Core so that you don’t have to manually do this)

Thanks @Chris White. I think this is not specific to prefect. I came across the same issue with Dask

@task

annotations.