https://prefect.io logo
Title
i

Ike

09/11/2019, 4:35 PM
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
c

Chris White

09/11/2019, 4:36 PM
Your pattern seems perfectly valid; could you share the errors you’re seeing?
i

Ike

09/11/2019, 4:39 PM
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
c

Chris White

09/11/2019, 4:42 PM
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
i

Ike

09/11/2019, 4:56 PM
Ahh thanks! Problem solved 👌🏾
c

Chris White

09/11/2019, 4:56 PM
💯
@Marvin archive “Issue with generating Sphinx documentation involving Prefect Tasks”
m

Marvin

09/11/2019, 4:56 PM
j

Jerry Thomas

09/12/2019, 4:17 PM
where should
my_task.__doc__ = my_task.run.__doc__
go? After the
@task
annotation or within the function or just anywhere in the file?
c

Chris White

09/12/2019, 4:20 PM
After the
@task
annotation
j

Jerry Thomas

09/13/2019, 8:52 AM
@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.
c

Chris White

09/13/2019, 3:57 PM
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__
j

Jerry Thomas

09/16/2019, 6:25 AM
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.
c

Chris White

09/16/2019, 4:12 PM
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)
j

Jerry Thomas

09/16/2019, 4:15 PM
Thanks @Chris White. I think this is not specific to prefect. I came across the same issue with Dask
@task
annotations.
👍 1