From 709ea7d430bd5ee27acda71d7f1f6f4192d0b8d3 Mon Sep 17 00:00:00 2001
From: Michael Ekstrand <mdekstrand@drexel.edu>
Date: Wed, 15 Jan 2025 22:00:35 -0500
Subject: [PATCH] document 2 ways to invoke pipelines

---
 docs/guide/pipeline.rst | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/docs/guide/pipeline.rst b/docs/guide/pipeline.rst
index c35dd52a7..14d8bd90a 100644
--- a/docs/guide/pipeline.rst
+++ b/docs/guide/pipeline.rst
@@ -326,11 +326,11 @@ The convenience methods are equivalent to the following pipeline code:
     # allow candidate items to be optionally specified
     items = pipe.create_input('items', ItemList, None)
     # look up a user's history in the training data
-    history = pipe.add_component('history-lookup', LookupTrainingHistory(), query=query)
+    history = pipe.add_component('history-lookup', LookupTrainingHistory, query=query)
     # find candidates from the training data
     default_candidates = pipe.add_component(
         'candidate-selector',
-        UnratedTrainingItemsCandidateSelector(),
+        UnratedTrainingItemsCandidateSelector,
         query=history,
     )
     # if the client provided items as a pipeline input, use those; otherwise
@@ -339,7 +339,7 @@ The convenience methods are equivalent to the following pipeline code:
     # score the candidate items using the specified scorer
     score = pipe.add_component('scorer', scorer, query=query, items=candidates)
     # rank the items by score
-    recommend = pipe.add_component('ranker', TopNRanker(50), items=score)
+    recommend = pipe.add_component('ranker', TopNRanker, {'n': 50}, items=score)
     pipe.alias('recommender', recommend)
     pipe.default_component('recommender')
     pipe = pipe.build()
@@ -464,6 +464,32 @@ Finally, you can directly pass configuration parameters to the component constru
 
 See :ref:`conventions` for more conventions for component design.
 
+Adding Components to the Pipeline
+---------------------------------
+
+You can add components to the pipeline in two ways:
+
+*   Instantiate the component with its configuration options and pass it to
+    :meth:`PipelineBuilder.add_component`::
+
+        builder.add_component('component-name', MyComponent(option='value'))
+
+    When you convert the pipeline into
+    a configuration or clone it, the component will be re-instantiated from its
+    configuration.
+
+*   Pass the component class and configuration separately to
+    :meth:`PipelineBuilder.add_component`::
+
+        builder.add_component('component-name', MyComponent, MyConfig(option='value'))
+
+    Alternatively::
+
+        builder.add_component('component-name', MyComponent, {'option': 'value'}))
+
+When you use the second approach, :meth:`PipelineBuilder.build` instantiates the
+component from the provided configuration.
+
 POPROX and Other Integrators
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~