fix quickstart guide

Author: thrau

docs/index.rst

@@ -6,9 +6,9 @@
 Plux - Dynamic Code Loading Framework
 =====================================
 
-Plux is the dynamic code loading framework used in `LocalStack <https://github.com/localstack/localstack>`_. It builds a higher-level plugin mechanism around `Python's entry point mechanism <https://packaging.python.org/specifications/entry-points/>`_.
+Plux is a plugin system for Python, and the dynamic code loading framework used in `LocalStack <https://github.com/localstack/localstack>`_. It builds a higher-level plugin mechanism around `Python's entry point mechanism <https://packaging.python.org/specifications/entry-points/>`_.
 
-Plux provides tools to load plugins from entry points at run time, and to discover entry points from plugins at build time (so you don't have to declare entry points statically in your ``setup.cfg`` or ``pyproject.toml``).
+Plux provides tools to load plugins from Python entry points at run time, and to discover entry points from plugins at build time (so you don't have to declare entry points statically in your ``setup.cfg`` or ``pyproject.toml``).
 
 .. image:: plux-architecture.png
    :alt: Plux Architecture

docs/user_guide/quickstart.rst

@@ -17,15 +17,13 @@ Core Concepts
 
 Before diving into the code, let's understand the core concepts of plux:
 
-* **Plugin**: An object that exposes ``should_load`` and ``load`` methods
-* **PluginSpec**: Describes a plugin with a namespace, name, and factory
-* **PluginManager**: Manages the runtime lifecycle of plugins
-* **PluginFinder**: Finds plugins at build time or runtime
+* **Plugin**: An object that has a namespace a name and exposes ``should_load`` and ``load`` methods
+* **PluginManager**: Manages the runtime lifecycle of plugins in a specific namespace
 
 Simple Plugin Example
 ---------------------
 
-Let's create a simple plugin and load it using the PluginManager.
+Let's create a simple plugin and load it using a ``PluginManager`` instance.
 
 1. Define a Plugin
 ~~~~~~~~~~~~~~~~~~
@@ -37,11 +35,14 @@ First, create a plugin by subclassing the ``Plugin`` class:
     from plux import Plugin
 
     class GreetingPlugin(Plugin):
-        namespace = "my.plugins.greetings"
-        name = "hello"
+        namespace = "my.plugins.greetings" # <- groups plugins together
+        name = "hello" # <- has to be unique within the namespace
         
         def load(self):
-            return "Hello, World!"
+            print("loading the plugin ...")
+
+        def greet(self):
+            return "Hello World!"
 
 2. Load the Plugin
 ~~~~~~~~~~~~~~~~~~
@@ -56,10 +57,13 @@ Now, let's use the ``PluginManager`` to load our plugin:
     manager = PluginManager("my.plugins.greetings")
     
     # Load the plugin by name
-    plugin = manager.load("hello")
+    plugin: GreetingPlugin = manager.load("hello")
     
     # The result is the return value of the plugin's load method
-    print(plugin)  # Output: Hello, World!
+    print(plugin.greet())  # Output: Hello, World!
+
+
+What's special about this is that the ``GreetingPlugin`` and the ``PluginManager`` can live in two separate python distributions.
 
 Function Plugin Example
 -----------------------
@@ -69,29 +73,54 @@ You can also create plugins from functions using the ``@plugin`` decorator:
 .. code-block:: python
 
     from plux import plugin
-    
-    @plugin(namespace="my.plugins.greetings")
-    def say_goodbye():
-        return "Goodbye, World!"
-    
+
+    @plugin(namespace="my.greeters")
+    def say_hallo():
+        print("hallo")
+
+    @plugin(namespace="my.greeters")
+    def say_hello():
+        print("hello")
+
+
+This defines two function plugins in the namespace ``my.greeters``, that can be loaded individually by their name, or in bulk.
+
+.. code-block:: python
+
     # Load the function plugin
-    manager = PluginManager("my.plugins.greetings")
-    goodbye_plugin = manager.load("say_goodbye")
-    
-    # Call the function plugin
-    print(goodbye_plugin())  # Output: Goodbye, World!
+    manager = PluginManager("my.configurators")
+
+    doc = dict()
+
+    # load a single plugin
+    greeter = manager.load("say_hello")
+    greeter() # prints "hello"
+
+    # load all of them
+    for greeter in manager.load_all():
+        greeter()
+
+
 
 Building and Discovering Plugins
 --------------------------------
 
-For plux to discover your plugins at runtime, you need to build entry points. The simplest way is to use the plux CLI:
+For plux to discover your plugins at runtime, you need to build entry points.
+The simplest way is to use the plux CLI:
 
 .. code-block:: bash
 
     # Generate entry points for your project
     python -m plux entrypoints
 
 This will scan your project for plugins and generate the necessary entry points.
+Then, when you run
+
+.. code-block:: bash
+
+    python -m build
+
+to build your distribution, it will contain the generated plugins.
 
 Next Steps
 ----------
@@ -100,4 +129,4 @@ This quickstart guide covered the basics of defining and loading plugins with pl
 
 * :doc:`defining_loading_plugins` - Learn more about different ways to define plugins
 * :doc:`plugin_manager` - Explore the PluginManager API in depth
-* :doc:`build_integration` - Understand how to integrate plux with your build system
+* :doc:`build_integration` - Understand how to integrate plux with your build system