Rework the docs intro and add another example

Rework the beginning of the docs answering three fundamental questions.

Instead of trying to cram everything into a highly compressed role definition, do the following:

Use 4 roles to introduce the basic concept from a bird's eye perspective - 3 of them are programs and one of them is a human (because why not?).

Instead of having only one example have two: the first example becomes
the "toy example" (because that's what it is). Add another example that
is showing two minimal projects (host and plugin), demonstrating the
concepts that would overwhelm the first toy example but are important
to understand conventions and get a complete picture.

Some additional changes in the docs:

* Flesh out the motivation for a system like pluggy a bit more.
* Turn "The pytest plugin system" from a heading into a tag-line.
* fix a pre existing title level problem
* add orphan tag to api reference to be able to build with warnings as errors
* turn doc build warnings into errors
* Made title casing more consistent

Author: obestwalter

docs/api_reference.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Api Reference
 =============
 

docs/examples/eggsample-spam/eggsample_spam.py

@@ -0,0 +1,16 @@
+import eggsample
+
+@eggsample.hookimpl
+def eggsample_add_ingredients(ingredients):
+    if len([e for e in ingredients if e == "egg"]) > 2:
+        ingredients.remove("egg")
+    spam = ["lovely spam", "wonderous spam", "splendiferous spam"]
+    print(f"add {spam}")
+    ingredients.extend(spam)
+
+@eggsample.hookimpl
+def eggsample_prep_condiments(condiments):
+    try:
+        del condiments["steak sauce"]
+    except KeyError:
+        pass

docs/examples/eggsample-spam/setup.py

@@ -0,0 +1,5 @@
+from setuptools import setup
+
+setup(name="eggsample-spam", install_requires="eggsample",
+      entry_points={'eggsample': ['spam = eggsample_spam']},
+      py_modules=['eggsample_spam'])

docs/examples/eggsample/eggsample/__init__.py

@@ -0,0 +1,7 @@
+import pluggy
+
+hookimpl = pluggy.HookimplMarker("eggsample")
+"""Marker to be imported and used in plugins"""
+
+pm = pluggy.PluginManager("eggsample")
+"""The manager ... you know? to manage the plugins!"""

docs/examples/eggsample/eggsample/hookspecs.py

@@ -0,0 +1,17 @@
+import pluggy
+
+hookspec = pluggy.HookspecMarker("eggsample")
+
+@hookspec
+def eggsample_add_ingredients(ingredients):
+    """Change the used ingredients.
+
+    :param list ingredients: the ingredients to be modified
+    """
+
+@hookspec
+def eggsample_prep_condiments(condiments):
+    """Reorganize the condiments tray.
+
+    :param dict condiments: some sauces and stuff
+    """

docs/examples/eggsample/eggsample/host.py

@@ -0,0 +1,32 @@
+import random
+
+from eggsample import hookimpl, hookspecs, lib, pm
+
+condiments_tray = {"pickled walnuts": 13, "steak sauce": 4, "mushy peas": 2}
+
+class FoodMaster2000:
+    def __init__(self):
+        self.ingredients = []
+
+    def add_ingredients(self):
+        pm.hook.eggsample_add_ingredients(ingredients=self.ingredients)
+
+    def prepare_the_food(self):
+        random.shuffle(self.ingredients)
+
+    def serve_the_food(self):
+        pm.hook.eggsample_prep_condiments(condiments=condiments_tray)
+        print(f"Your food: {', '.join(self.ingredients)}")
+        print(f"Some condiments: {', '.join(condiments_tray.keys())}")
+
+def main():
+    pm.add_hookspecs(hookspecs)
+    pm.load_setuptools_entrypoints("eggsample")
+    pm.register(lib)
+    fm2000 = FoodMaster2000()
+    fm2000.add_ingredients()
+    fm2000.prepare_the_food()
+    fm2000.serve_the_food()
+
+if __name__ == '__main__':
+    main()

docs/examples/eggsample/eggsample/lib.py

@@ -0,0 +1,11 @@
+import eggsample
+
+@eggsample.hookimpl
+def eggsample_add_ingredients(ingredients):
+    basics = ["egg", "egg", "salt", "pepper"]
+    print(f"Add {basics}")
+    ingredients.extend(basics)
+
+@eggsample.hookimpl
+def eggsample_prep_condiments(condiments):
+    condiments["mint sauce"] = 1

docs/examples/eggsample/setup.py

@@ -0,0 +1,5 @@
+from setuptools import setup, find_packages
+
+setup(name="eggsample", install_requires="pluggy>=0.3,<1.0",
+      entry_points={'console_scripts': ['eggsample=eggsample.host:main']},
+      packages=find_packages())