Merge pull request #675 from pyiron/extend_workflow_docs

Add a doc example for workflow inputs and outputs

pyiron_contrib/workflow/workflow.py

@@ -85,19 +85,53 @@ class Workflow(HasToDict):
         >>> print(wf.my_node.inputs.x, wf.my_node0.inputs.x, wf.my_node1.inputs.x)
         0, 1, 2
 
-        We can also use pre-built nodes, e.g.
-        >>> from pyiron_contrib.workflow.node_library import atomistics, standard
+        The `Workflow` class is designed as a single point of entry for workflows, so
+        you can also access decorators to define new node classes right from the
+        workflow (cf. the `Node` docs for more detail on the node types).
+        Let's use these to explore a workflow's input and output, which are dynamically
+        generated from the unconnected IO of its nodes:
+        >>> @Workflow.wrap_as.fast_node("y")
+        >>> def plus_one(x: int = 0):
+        ...     return x + 1
         >>>
+        >>> wf = Workflow("io_workflow")
+        >>> wf.first = plus_one()
+        >>> wf.second = plus_one()
+        >>> print(len(wf.inputs), len(wf.outputs))
+        2 2
+
+        If we connect the output of one node to the input of the other, there are fewer
+        dangling channels for the workflow IO to find:
+        >>> wf.second.inputs.x = wf.first.outputs.y
+        >>> print(len(wf.inputs), len(wf.outputs))
+        1 1
+
+        The workflow joins node lavels and channel labels with a `_` character to
+        provide direct access to the output:
+        >>> print(wf.outputs.second_y.value)
+        2
+
+        Workflows also give access to packages of pre-built nodes under different
+        namespaces, e.g.
         >>> wf = Workflow("with_prebuilt")
         >>>
-        >>> wf.structure = atomistics.BulkStructure(repeat=3, cubic=True, element="Al")
+        >>> wf.structure = wf.add.atomistics.BulkStructure(
+        ...     repeat=3,
+        ...     cubic=True,
+        ...     element="Al"
+        ... )
         >>> wf.engine = atomistics.Lammps(structure=wf.structure)
-        >>> wf.calc = atomistics.CalcMD(job=wf.engine)
+        >>> wf.calc = atomistics.CalcMd(
+        ...     job=wf.engine,
+        ...     run_on_updates=True,
+        ...     update_on_instantiation=True,
+        ... )
         >>> wf.plot = standard.Scatter(
         ...     x=wf.calc.outputs.steps,
         ...     y=wf.calc.outputs.temperature
         ... )
 
+    TODO: Registration of new node packages
 
     TODO: Workflows can be serialized.