Clean Up Documentation (#20)

Author: scottoffen

docs/docs/describe-pipelines.md

@@ -40,6 +40,14 @@ Example output:
 ]
 ```
 
+:::warning Warning
+
+The `Order` value in the JSON output represents the execution order of the steps. This value is assigned based on the order in which the steps will be executed, and it may differ from the `Order` specified in each step's `PipelineStep` attribute.
+
+For example, if you have only two steps with `PipelineStep(Order = 3)` and `PipelineStep(Order = 4)`, the JSON output will show `Order` values of `0` and `1`, respectively - reflecting their relative execution sequence, not their original attribute values.
+
+:::
+
 ## Instantiation Behavior
 
 Calling `Describe()` **will instantiate all steps** in the pipeline by accessing their `Lazy<T>` wrappers. This may result in constructor injection or other side effects associated with instantiating the step class. Use this method only when you are prepared for that overhead.

docs/docs/diagnostics.md

@@ -46,4 +46,4 @@ listener.Subscribe(new Observer((name, payload) =>
 
 ## Conclusion
 
-PipeForge diagnostics give you deep visibility into pipeline execution with minimal effort. Whether you’re debugging a failing step or building runtime instrumentation, the diagnostics hooks are ready to help.
+PipeForge diagnostics give you deep visibility into pipeline execution with minimal effort. Whether you're debugging a failing step or building runtime instrumentation, the diagnostics hooks are ready to help.

docs/docs/index.md

@@ -9,7 +9,7 @@ PipeForge is a lightweight, composable, lazy-instantiation pipeline framework fo
 
 Pipelines operate on a specific class known as the **context**. Each pipeline step is a discrete unit of work, written in code and annotated with metadata indicating its order and (optional) filter. These steps are lazily instantiated and executed in sequence by the pipeline runner.
 
-At any point, the pipeline can **short-circuit**, halting execution — and preventing the instantiation of any remaining steps.
+At any point, the pipeline can **short-circuit**, halting execution - and preventing the instantiation of any remaining steps.
 
 ## Sample Context
 
@@ -40,10 +40,10 @@ public class SampleContext
 ```
 
 This context allows us to:
-- Track pipeline progress via AddStep()
-- Print execution history using ToString()
-- Assert how many steps ran using StepCount
-- Simulate errors by passing invalid step names
+- Track pipeline progress via `AddStep()`
+- Print step execution history using `ToString()`
+- Assert how many steps ran using `StepCount`
+- Simulate errors by passing null or empty step names
 
 ## Installation
 

docs/docs/manual-composition.md

@@ -0,0 +1,90 @@
+---
+sidebar_position: 7
+title: Manual Composition
+---
+
+# Manual Composition
+
+PipeForge is designed to integrate seamlessly with dependency injection, but it's flexible enough to support manual composition. This can be useful in testing scenarios, minimal environments, or when you need full control over pipeline configuration.
+
+The main drawbacks of this approach are that you'll be responsible for manually instantiating all dependencies for each step, and the resulting pipeline may not accurately reflect the behavior of your production configuration.
+
+## Creating a Pipeline
+
+Manual pipeline composition is straightforward using the fluent API exposed by `PipelineBuilder<T>`, which is returned from the static method `Pipeline.CreateFor<T>()`. You can optionally pass an `ILoggerFactory` to enable logging during execution by the resulting `PipelineRunner<T>`.
+
+Add steps to the pipeline in the desired execution order using the fluent, chainable methods:
+
+- `Add<TStep>()` - for steps with a parameterless constructor
+- `AddStep<TStep>(Func<TStep> factory)` - for steps that require constructor parameters
+
+```csharp title="Steps Used"
+private abstract class TestStep : PipelineStep<SampleContext>
+{
+    public override async Task InvokeAsync(
+        SampleContext context,
+        PipelineDelegate<SampleContext> next,
+        CancellationToken cancellationToken = default)
+    {
+        context.AddStep(Name);
+        await next(context, cancellationToken);
+    }
+}
+
+private class StepA : TestStep
+{
+    public StepA() => Name = "A";
+}
+
+private class StepB : TestStep
+{
+    public StepB() => Name = "B";
+}
+
+private class StepC : TestStep
+{
+    public StepC() => Name = "C";
+}
+
+private class StepD : TestStep
+{
+    public StepD(string name) => Name = name;
+}
+```
+
+Note that `StepD` lacks a parameterless constructor, which means it can't be added using `Add<TStep>()`. Instead, you'll need to use `AddStep<TStep>(Func<TStep>)` to manually supply its dependencies - for example, if the step requires a configuration value, a logger, or a service instance.
+
+```csharp title="Manual Pipeline Setup"
+var stepName = "Hello";
+var pipeline = Pipeline.CreateFor<SampleContext>()
+    .WithStep<StepA>()
+    .WithStep<StepB>()
+    .WithStep<StepC>()
+    .WithStep(() => new StepD(stepName))
+    .Build();
+
+var context = new SampleContext();
+await pipeline.ExecuteAsync(context);
+
+Console.WriteLine(context);
+// Should be:
+// A,B,C,Hello
+```
+
+## Advanced Scenarios
+
+In more advanced scenarios, the factory delegate can create a scope and resolve dependencies from the scoped service provider before constructing the step. This is especially useful when the step relies on services with scoped lifetimes, such as per-request context or transient infrastructure components. For example:
+
+```
+builder.WithStep(() =>
+{
+    using var scope = serviceProvider.CreateScope();
+    var scopedProvider = scope.ServiceProvider;
+    var name = scopedProvider.GetRequiredService<IOptions<MySettings>>().Value.Name;
+    return new StepD(name);
+});
+```
+
+## Conclusion
+
+Manual composition allows you to build and run a pipeline without relying on a DI container. While this approach is less common for production use, it provides maximum control for configuration, **testing** and minimal-host scenarios.

docs/docs/manual-wiring.md

@@ -21,7 +21,7 @@ The optional metadata properties do not impact step registration or execution, b
 
 :::tip[Tip]
 
-Because pipeline steps are plain classes, you can inject dependencies through their constructors - enabling full integration with your existing services, business logic, and data access layers.
+Because pipeline steps are plain classes, you can **inject dependencies** through their constructors - enabling full integration with your existing services, business logic, and data access layers.
 
 :::
 
@@ -73,7 +73,7 @@ public class ShortCircuitStep : PipelineStep<StepContext>
 
 ## Adding the `[PipelineStep]` Attribute
 
-To be discoverable, each pipeline step must be decorated with the [PipelineStep] attribute. This attribute defines the order in which pipeline steps should execute.
+To be discoverable, each pipeline step must be decorated with the `[PipelineStep]` attribute. This attribute defines the order in which pipeline steps should execute.
 
 ```csharp title="Step1.cs"
 [PipelineStep(1)]
@@ -85,14 +85,14 @@ public class Step1 : PipelineStep<SampleContext>
 
 :::tip[Tip]
 
-- Multiple steps that are not using the same context will not be impacted by using the same order value.
-- Multiple steps that are using the same context and have the same order value will be ordered arbitrarily.
+- Multiple steps that are **not** using the same context will not be impacted by using the same order value.
+- Multiple steps that **are** using the same context and have the same order value will be ordered arbitrarily.
 
 :::
 
 ### Adding a Step Filter
 
-You can limit when a step will be registered in by adding the `Filter` parameter to the `PipelineStep` attribute. This is useful to add steps that will only be registered when the `Development` filter is applied.
+You can limit when a step will be registered by adding the `Filter` parameter to the `PipelineStep` attribute. This is useful to ensure that some steps will only be registered when the filter is applied during step discovery and registration.
 
 ```csharp title="Step2.cs"
 [PipelineStep(2, "Development")]
@@ -104,8 +104,8 @@ public class Step2 : PipelineStep<SampleContext>
 
 :::danger[Caution]
 
-- Steps that do NOT have an `Filter` parameter in the attribute will always be registered during the step discovery process. 
-- Steps that DO have an `Filter` parameter in the attribute will only be registered if the same value is passed to the [registration extension method](./step-discovery.md).
+- Steps **without** a `Filter` parameter will always be registered during the step discovery and registration process. 
+- Steps **with** `Filter` parameter will only be registered if the same value is passed to the [registration extension method](./step-discovery.md).
 
 :::
 

docs/docs/pipeline-steps.md

@@ -33,7 +33,7 @@ public class StepB : PipelineStep<StepContext>
 }
 
 [PipelineStep(3)]
-public class StepA : PipelineStep<StepContext>
+public class StepC : PipelineStep<StepContext>
 {
     public override async Task InvokeAsync(StepContext context, PipelineDelegate<StepContext> next, CancellationToken cancellationToken = default)
     {
@@ -46,12 +46,12 @@ var context = new SampleContext();
 var services = new ServiceCollection();
 services.AddPipelineFor<SampleContext>();
 
-var provider = services.BuildServiceProvider()
+var provider = services.BuildServiceProvider();
 var runner = provider.GetRequiredService<IPipelineRunner<SampleContext>>();
 
 await runner.ExecuteAsync(context);
 
-Console.WriteLine(context.ToString()); // e.g. "A1,A2,B1"
+Console.WriteLine(context.ToString()); // e.g. "A1,B2,C3"
 ```
 
 Each registered pipeline step for `SampleContext` will be executed in order, unless short-circuited by a step that chooses not to call `next()`.

docs/docs/running-pipelines.md

@@ -9,7 +9,7 @@ In order to ensure that pipeline steps are both registered correctly and registe
 
 ## Using the Extension Method
 
-When the extension method is called using only the type parameter `T`, it will scan all assemblies in the AppDomain for classes that implement `IPipelineStep<T>` and have the `PipelineStep` attribute that does not specify a filter. It will then register all matching classes in the dependency injection container - along with an instance of `IPipelineRunner<T>` - with a transient service lifetime.
+When the extension method is called using only the type parameter `T`, it will scan all assemblies in the `AppDomain` for classes that implement `IPipelineStep<T>` and have a `PipelineStep` attribute that does not specify a filter. It will then register all matching classes in the dependency injection container - along with an instance of `IPipelineRunner<T>` - with a transient service lifetime.
 
 ```csharp
 services.AddPipelineFor<SampleContext>();
@@ -21,10 +21,10 @@ The extension method takes optional parameters to change the service lifetime or
 // Add services using a scoped service lifetime
 services.AddPipelineFor<SampleContext>(ServiceLifetime.Scoped);
 
-// Include steps explicitly marked with the "Development" filter
+// Include steps with the "Development" filter
 service.AddPipelineFor<SampleContext>("Development");
 
-// Use a scoped lifetime and include marked with the "Development" filter
+// Use a scoped lifetime and include steps with the "Development" filter
 service.AddPipelineFor<SampleContext>(ServiceLifetime.Scoped, "Development");
 ```
 
@@ -43,7 +43,11 @@ public class ManuallyRegisterStep : PipelineStep<StepContext>
 services.AddPipelineStep<ManuallyRegisterStep>(ServiceLifetime.Scoped);
 ```
 
-Using this extension method will NOT register a corresponding instance of `IPipelineRunner<T>`.
+:::tip Note
+
+Using this extension method will **not** register a corresponding instance of `IPipelineRunner<T>`.
+
+:::
 
 ## Conclusion
 

docs/docs/step-discovery.md

@@ -30,5 +30,5 @@ if ($IsWindows) {
 } elseif ($IsLinux) {
     xdg-open $indexPath
 } else {
-    Write-Warning "Platform not detected — open coverage-report/index.html manually"
+    Write-Warning "Platform not detected - open coverage-report/index.html manually"
 }