User Documentation Proposal

[pingsutw]

TL;DR

• Design docs
• Add description entity model
• Add a new attribute docs to the task / workflow
• Add a new attribute docs to the taskSpec / workflowSpec, so description entity will be registered when we register a task or workflow

Two ways to add documentation for the task

1. In decorator

@task(docs=Documentation(short_description="hello world", long_description=LongDescription(uri="s3://bucket/file"), source_code=SourceCode("https://github/flytekit")))
def t1(a: int) -> int:
    ...

2. In comment

@task
def t1(a: int) -> int:
    """
    Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature.
    """
    return a

Type

• [ ] Bug Fix
• [x] Feature
• [ ] Plugin

Are all requirements met?

• [x] Code completed
• [x] Smoke tested
• [x] Unit tests added
• [ ] Code documentation added
• [ ] Any pending items have an associated Issue

Complete description

^^^

Tracking Issue

https://github.com/flyteorg/flyte/issues/531

Follow-up issue

NA

[codecov[bot]]

Codecov Report

Merging #1200 (c5b7143) into master (d008917) will decrease coverage by 0.06%. The diff coverage is 56.60%.

@@            Coverage Diff             @@
##           master    #1200      +/-   ##
==========================================
- Coverage   69.24%   69.18%   -0.07%     
==========================================
  Files         297      299       +2     
  Lines       27847    27996     +149     
  Branches     2616     2631      +15     
==========================================
+ Hits        19282    19368      +86     
- Misses       8054     8114      +60     
- Partials      511      514       +3     

Impacted Files	Coverage Δ
flytekit/configuration/__init__.py	36.63% <0.00%> (-0.25%)	:arrow_down:
flytekit/configuration/file.py	56.21% <0.00%> (ø)
flytekit/core/interface.py	61.80% <ø> (ø)
flytekit/core/task.py	34.88% <0.00%> (-0.84%)	:arrow_down:
setup.py	0.00% <ø> (ø)
flytekit/models/documentation.py	15.38% <15.38%> (ø)
flytekit/models/admin/workflow.py	28.84% <28.57%> (+2.75%)	:arrow_up:
flytekit/core/base_task.py	46.24% <33.33%> (-0.65%)	:arrow_down:
flytekit/core/workflow.py	60.34% <33.33%> (-0.98%)	:arrow_down:
flytekit/models/task.py	36.15% <50.00%> (+0.35%)	:arrow_up:
... and 9 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[flixr]

Nice! But what about e.g. a ContainerTask?

[pingsutw]

Nice! But what about e.g. a ContainerTask?

We can add description to all kind of the tasks.