Improve the output and make clearer, why we do what we do in docs.

Author: obestwalter

docs/examples/eggsample-spam/eggsample_spam.py

@@ -2,20 +2,19 @@
 
 @eggsample.hookimpl
 def eggsample_add_ingredients(ingredients):
-    """Here we get an immutable object, so we return something to the caller."""
+    """Here the caller expects us to return a list."""
     if "egg" in ingredients:
         spam = ["lovely spam", "wonderous spam"]
     else:
         spam = ["splendiferous spam", "magnificent spam"]
-    print(f"Add {spam}")
     return spam
 
 @eggsample.hookimpl
 def eggsample_prep_condiments(condiments):
-    """Here we get a mutable object, so we just mess with it directly."""
+    """Here the caller passes a mutable object, so we mess with it directly."""
     try:
         del condiments["steak sauce"]
     except KeyError:
         pass
     condiments['spam sauce'] = 42
-    print(f"Now. this is what I call a condiments tray!")
+    return f"Now this is what I call a condiments tray!"

docs/examples/eggsample/eggsample/hookspecs.py

@@ -15,5 +15,5 @@ def eggsample_prep_condiments(condiments: dict):
     """Reorganize the condiments tray to your heart's content.
 
     :param condiments: some sauces and stuff
-    :return: will be ignored by caller
+    :return: a witty comment about your activity
     """

docs/examples/eggsample/eggsample/host.py

@@ -40,9 +40,12 @@ def prepare_the_food(self):
         random.shuffle(self.ingredients)
 
     def serve_the_food(self):
-        self.hook.eggsample_prep_condiments(condiments=condiments_tray)
-        print(f"Your food: {', '.join(self.ingredients)}")
-        print(f"Some condiments: {', '.join(condiments_tray.keys())}")
+        condiment_comments = self.hook.eggsample_prep_condiments(
+            condiments=condiments_tray)
+        print(f"Your food. Enjoy some {', '.join(self.ingredients)}")
+        print(f"Some condiments? We have {', '.join(condiments_tray.keys())}")
+        if any(condiment_comments):
+            print("\n".join(condiment_comments))
 
 if __name__ == '__main__':
     main()

docs/examples/eggsample/eggsample/lib.py

@@ -5,7 +5,6 @@ def eggsample_add_ingredients():
     spices = ["salt", "pepper"]
     you_can_never_have_enough_eggs = ["egg", "egg"]
     ingredients = spices + you_can_never_have_enough_eggs
-    print(f"Add {ingredients}")
     return ingredients
 
 @eggsample.hookimpl

docs/index.rst

@@ -127,9 +127,8 @@ Let's get cooking - we install the host and see what a program run looks like::
     $ pip install --editable pluggy/docs/examples/eggsample
     $ eggsample
 
-    Add ['salt', 'pepper', 'egg', 'egg']
-    Your food: pepper, egg, egg, egg, egg, salt, egg
-    Some condiments: pickled walnuts, steak sauce, mushy peas, mint sauce
+    Your food. Enjoy some egg, egg, salt, egg, egg, pepper, egg
+    Some condiments? We have pickled walnuts, steak sauce, mushy peas, mint sauce
 
 The plugin
 ^^^^^^^^^^
@@ -147,11 +146,9 @@ we get::
     $ pip install --editable pluggy/docs/examples/eggsample-spam
     $ eggsample
 
-    Add ['salt', 'pepper', 'egg', 'egg']
-    Add ['lovely spam', 'wonderous spam']
-    Now, this is what I call a condiments tray!
-    Your food: wonderous spam, pepper, egg, egg, egg, egg, lovely spam, egg, salt
-    Some condiments: pickled walnuts, mushy peas, mint sauce, spam sauce
+    Your food. Enjoy some egg, lovely spam, salt, egg, egg, egg, wonderous spam, egg, pepper
+    Some condiments? We have pickled walnuts, mushy peas, mint sauce, spam sauce
+    Now this is what I call a condiments tray!
 
 More real world examples
 ------------------------