Page MenuHomeElementl

update solid concepts page to use less boilerplate
ClosedPublic

Authored by sandyryza on Apr 10 2021, 4:20 PM.

Details

Summary

The main change is to use less boilerplate in the code snippets that describe inputs and outputs.
Users should only be using InputDefinitions and OutputDefinitions when they're needed.

It also:

  • De-emphasizes solid reusability.
  • Removes the examples, which were redundant with the examples in the explanatin sections. I think it would be helpful to later add examples that showcase somewhat more complicated functionality.
Test Plan

bk

Diff Detail

Repository
R1 dagster
Branch
solid-overview (branched from master)
Lint
Lint Passed
Unit
No Test Coverage

Event Timeline

Harbormaster returned this revision to the author for changes because remote builds failed.Apr 10 2021, 4:48 PM
Harbormaster failed remote builds in B28683: Diff 35206!
Harbormaster returned this revision to the author for changes because remote builds failed.Apr 10 2021, 5:51 PM
Harbormaster failed remote builds in B28684: Diff 35207!
Harbormaster returned this revision to the author for changes because remote builds failed.Apr 10 2021, 10:52 PM
Harbormaster failed remote builds in B28685: Diff 35209!
sandyryza added reviewers: owen, sashank.
sandyryza edited the summary of this revision. (Show Details)
Harbormaster returned this revision to the author for changes because remote builds failed.Apr 12 2021, 3:21 PM
Harbormaster failed remote builds in B28687: Diff 35211!

agreed with removing unnecessary InputDefinitions and OutputDefinitions when introducing inputs and outputs.
but i'd suggest explaining InputDefinition and OutputDefinition more in the explanation sections.

docs/content/concepts/solids-pipelines/solids.mdx
52–53

maybe move this section to be after the Inputs and Outputs section

71

[1]

80–89

i think here we'd want to explain InputDefinition itself and its benefits (which aren't fully mentioned here): benefits include descriptions, default value, and types.

this example is good but i would probably move this to the Examples section, bc it's explaining two features at the same time (customizing DagsterType and defining InputDefinition) which isn't a minimum requirement that users should know about solid inputs.

we may want an example only about InputDefinition itself and explain that users can from the simplest my_input_solid to specifying InputDefinition and then benefit from InputDefinition's properties like dagster_type for typing inputs, explict naming and description for documenting computations, etc.

@solid(
    input_defs=[
        InputDefinition(name="abc", dagster_type=str, description="Some description"),
        InputDefinition(name="xyz", dagster_type=int, description="Some description"),
    ]
)
def my_input_example_solid(context, abc, xyz):
    pass
93

nit: "result." -> "result".

docs/content/concepts/solids-pipelines/solids.mdx
52–53

good idea

80–89

At this point, I think the main reason to use InputDefinition would only be to use "advanced" features like dagster types or IOManager metadata. If someone wants to attach descriptions and default values to inputs, they can do it like this (we parse the docstring):

@solid
def my_input_example_solid(context, abc: str, xyz: int = 5):
    """
    Args:
        abc: Some description
        xyz: Some description
    """

Thoughts on the right direction? I agree that it's a little weird to introduce types and InputDefinitions at the same time, but I don't want to lead users to believe they need to use InputDefinitions in situations where they don't. We could possibly just omit them entirely from this page and only mention them on the Dagster Type and IOManager pages?

93

thanks for catching

This revision is now accepted and ready to land.Apr 15 2021, 7:18 PM