Create Documentation (#13)

* Remove landing page

* Add documentation

* Add project image assets

Author: scottoffen

CONTRIBUTING.md

@@ -1,13 +1,12 @@
 # Contributing to PipeForge
 
-PipeForge has received lots of great feedback from the community. We've used this feedback to inform the direction of the project, and we absolutely want to keep hearing from you! **Your involvement makes the project better** by increasing the usability, quality and adoption of the project. Our goal is to be better stewards by being more responsive and transparent. Following the contribution guidelines outlined below will help us to better help you.
+Community feedback is used to inform the direction of the project, and we absolutely want to hear from you! **Your involvement makes the project better** by increasing the usability, quality and adoption of the project. Our goal is to be better stewards by being more responsive and transparent. Following the contribution guidelines outlined below will help us to better help you.
 
 # How To Get Help
 
 A lot of issues that were created in previous versions of PipeForge were not bugs or feature requests, they were questions or discussions - most of which could be (and were) answered by anyone in the community; they're not exclusive to the maintainers. For feedback like this, there are several places where people can get all kinds of help, and we would encourage you to use them first.
 
 - Consult the [official documentation](https://scottoffen.github.io/PipeForge).
-- Take a gander at the [Samples](https://github.com/scottoffen/PipeForge/tree/main/src/Samples) project.
 - Engage in our [community discussions](https://github.com/scottoffen/PipeForge/discussions).
 - Ask your question on [StackOverflow](https://stackoverflow.com) using [#PipeForge](https://stackoverflow.com/questions/tagged/PipeForge?sort=newest).
 
@@ -27,8 +26,6 @@ Regardless of whether you are opening a bug report, asking a question on StackOv
 
 Got an idea on how to make PipeForge better? Start or join a conversation in our [community discussions](https://github.com/scottoffen/PipeForge/discussions) and suggest your change there. **Do not open an issue on GitHub until** you have collected positive feedback about the change. Where it comes to improvements, we want to ensure we are focused on solving problems, not attacking symptoms, while remaining focused on our guiding principles: fast, unopinionated, and minimalist. In a word: simple.
 
-That being said, PipeForge is designed to make it easy to add middleware at different places in the server and request/response pipeline. You can also create your own implementations of the different interfaces and inject them. All told, that makes it easy to take your functionality and put it in a package that can be used by others as an add-on or plugin to the core PipeForge library, rather than in the core library, if that makes more sense.
-
 If it is decided that your idea would be a good inclusion to the core PipeForge project, create a feature request issue based on the outcome of the community discussion.
 
 # Issue Management
@@ -71,8 +68,8 @@ Changes that are cosmetic in nature and do not add anything substantial to the s
 - It creates a lot of notification noise
 - It pollutes the git history
 
-Sometimes, your editor will completely reformat a file when you save it, making numerous white space changes that, while they don't affect the code, create a lot of noise for the reviewers. If this happens, the PR will not be considered until those white space changes are removed.
+Sometimes, your editor may completely reformat a file when you save it, making numerous white space changes that, while they don't affect the code, create a lot of noise for the reviewers. If this happens, the PR will not be considered until those white space changes are reverted.
 
 # Documentation Changes
 
-Having excellent documentation is crucial to the success of PipeForge. Documentation for PipeForge lives in [docs](). Your contribution of clear, concise and accurate documentation is appreciated.
+Having excellent documentation is crucial to the success of PipeForge. Documentation for PipeForge is written using [Docusaurus](https://docusaurus.io/), lives in [docs folder](./docs/). Your contribution of clear, concise and accurate documentation is appreciated.

docs/docs/describe-pipelines.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 6
+title: Describing Pipelines
+---
+
+# Describing Pipelines
+
+The `Describe()` method on `IPipelineRunner<T>` is used to inspect and document the pipeline configuration at runtime. It returns a JSON string describing each registered pipeline step.
+
+This method is useful for diagnostics, tooling, and dynamically displaying pipeline behavior in user interfaces or logs - but only if you've taken the time to add the necessary metadata to your step classes.
+
+## Output Format
+
+The JSON output contains an array of objects, each representing a pipeline step with the following fields:
+
+* `Order`: The zero-based order in which the step appears in the pipeline
+* `Name`: The value of the step's `Name` property
+* `Description`: The step's `Description`, if defined
+* `MayShortCircuit`: A boolean indicating whether the step might short-circuit execution
+* `ShortCircuitCondition`: The value of the step's `ShortCircuitCondition`, if any
+
+Example output:
+
+```json
+[
+  {
+    "Order": 0,
+    "Name": "ValidateInput",
+    "Description": "Checks that required values are present",
+    "MayShortCircuit": true,
+    "ShortCircuitCondition": "Invalid input"
+  },
+  {
+    "Order": 1,
+    "Name": "TransformData",
+    "Description": "Prepares data for downstream steps",
+    "MayShortCircuit": false,
+    "ShortCircuitCondition": null
+  }
+]
+```
+
+## 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.
+
+## Use Cases
+
+* Logging pipeline structure for observability
+* Generating runtime documentation or UI
+* Verifying step order and metadata during tests or builds
+
+If you need to inspect step configuration without triggering instantiation, consider maintaining parallel metadata or restricting usage of `Describe()` to controlled environments.
+
+## Conclusion
+
+Use `Describe()` to introspect your pipeline at runtime, but be aware that it will force full resolution of every registered step.

docs/docs/diagnostics.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 8
+title: Diagnostics
+---
+
+# Diagnostics
+
+PipeForge includes built-in diagnostics via the [`System.Diagnostics.DiagnosticSource`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.diagnosticsource) API. This allows you to observe pipeline execution without modifying your steps.
+
+## Emitted Events
+
+The pipeline emits the following diagnostic events for each step:
+
+| Event Name           | Description                                                      |
+| -------------------- | ---------------------------------------------------------------- |
+| `PipelineStep.Start` | Emitted **before** a step is invoked. Payload includes the step. |
+| `PipelineStep.Stop`  | Emitted **after** a step completes. Payload includes the step.   |
+
+All events are emitted under a listener name in the format:
+
+```
+PipeForge.PipelineRunner<TContext>
+```
+
+You can subscribe to these events to monitor or trace execution flow.
+
+## Example: Listening for Events
+
+Here's an example of a diagnostic listener that logs every start and stop event:
+
+```csharp
+using System.Diagnostics;
+
+var listener = new DiagnosticListener("PipeForge.PipelineRunner<SampleContext>");
+listener.Subscribe(new Observer((name, payload) =>
+{
+    Console.WriteLine($"{name}: {payload}");
+}));
+```
+
+## Integration Tips
+
+* You can use this mechanism to generate timing metrics, debug issues, or visualize step execution.
+* Diagnostic events are low-overhead and safe to leave enabled in production.
+* Combine this with the `Describe()` method for a full picture of pipeline structure and execution behavior.
+
+## 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.

docs/docs/index.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 1
+title: Getting Started
+---
+
+# Welcome to PipeForge
+
+PipeForge is a lightweight, composable, lazy-instantiation pipeline framework for .NET. It simplifies step-based processing while remaining discoverable and testable. Inspired by middleware pipelines and modern dependency injection patterns, PipeForge gives you structured control over sequential logic flows - without the ceremony.
+
+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) environment. 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.
+
+## Sample Context
+
+For the purposes of this documentation, the following sample context will be used.
+
+```csharp title="SampleContext.cs"
+public class SampleContext
+{
+    private readonly List<string> _steps = new();
+
+    public void AddStep(string stepName)
+    {
+        if (string.IsNullOrWhiteSpace(stepName))
+        {
+            throw new ArgumentException("Step name cannot be null or whitespace.", nameof(stepName));
+        }
+
+        _steps.Add(stepName);
+    }
+
+    public int StepCount => _steps.Count;
+
+    public override string ToString()
+    {
+        return string.Join(",", _steps);
+    }
+}
+```
+
+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
+
+## Installation
+
+PipeForge is available on [NuGet.org](https://www.nuget.org/packages/PipeForge/) and can be installed using a NuGet package manager or the .NET CLI.
+
+PipeForge targets `.NET Standard 2.0` for broad compatibility, and also multi-targets `.NET 5.0` to take advantage of modern runtime features where available.

docs/docs/intro.md

@@ -0,0 +1,65 @@
+---
+sidebar_position: 7
+title: Manual Wiring
+---
+
+# Using PipeForge Without Dependency Injection
+
+PipeForge is designed to integrate smoothly with dependency injection, but it's flexible enough to be used without it. Manual wiring may be useful in testing scenarios, lightweight environments, or when you want full control over pipeline composition.
+
+## Manually Constructing a Pipeline
+
+You can manually create a list of steps and pass them to a `PipelineRunner<T>`. Each step should be wrapped in a `Lazy<IPipelineStep<T>>` to maintain compatibility with PipeForge's lazy instantiation pattern.
+
+```csharp title="Manual Pipeline Setup"
+public class StepA : PipelineStep<SampleContext>
+{
+    public StepA() => Name = "A";
+
+    public override async Task InvokeAsync(SampleContext context, PipelineDelegate<SampleContext> next, CancellationToken cancellationToken = default)
+    {
+        context.AddStep(Name);
+        await next(context, cancellationToken);
+    }
+}
+
+public class StepB : PipelineStep<SampleContext>
+{
+    public StepB() => Name = "B";
+
+    public override async Task InvokeAsync(SampleContext context, PipelineDelegate<SampleContext> next, CancellationToken cancellationToken = default)
+    {
+        context.AddStep(Name);
+        await next(context, cancellationToken);
+    }
+}
+
+public class StepC : PipelineStep<SampleContext>
+{
+    public StepShortCircuit() => Name = "C";
+
+    public override Task InvokeAsync(SampleContext context, PipelineDelegate<SampleContext> next, CancellationToken cancellationToken = default)
+    {
+        context.AddStep(Name);
+        await next(context, cancellationToken);
+    }
+}
+
+var steps = new List<Lazy<IPipelineStep<SampleContext>>>
+{
+    new(() => new StepA()),
+    new(() => new StepC()),
+    new(() => new StepB())
+};
+
+var runner = new PipelineRunner<SampleContext>(steps);
+
+var context = new SampleContext();
+await runner.ExecuteAsync(context);
+
+Console.WriteLine($"Final context: {context}");
+```
+
+## Conclusion
+
+Manual wiring 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 testing and minimal-host scenarios.