Updates docs structure to prepare for Github Pages (#1581)

App-vNext · Sep 12, 2023 · 6e69ec3 · 6e69ec3
1 parent c20e817
commit 6e69ec3
Show file tree

Hide file tree

Showing 13 changed files with 109 additions and 98 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -6,79 +6,6 @@ We are a member of the [.NET Foundation](https://www.dotnetfoundation.org/about)
 
 ![Polly logo](https://raw.github.com/App-vNext/Polly/main/Polly-Logo.png)
 
-## Quick start
-
-To use Polly, you must provide a callback and execute it using [**resilience pipeline**](resilience-pipelines.md). A resilience pipeline is a combination of one or more [**resilience strategies**](resilience-strategies.md) such as retry, timeout, and rate limiter. Polly uses **builders** to integrate these strategies into a pipeline.
-
-To get started, first add the [Polly.Core](https://www.nuget.org/packages/Polly.Core/) package to your project by running the following command:
-
-```sh
-dotnet add package Polly.Core
-```
-
-You can create a `ResiliencePipeline` using the `ResiliencePipelineBuilder` class as shown below:
-
-<!-- snippet: quick-start -->
-```cs
-// Create a instance of builder that exposes various extensions for adding resilience strategies
-var builder = new ResiliencePipelineBuilder();
-
-// Add retry using the default options
-builder.AddRetry(new RetryStrategyOptions());
-
-// Add 10 second timeout
-builder.AddTimeout(TimeSpan.FromSeconds(10));
-
-// Build the resilience pipeline
-ResiliencePipeline pipeline = builder.Build();
-
-// Execute the pipeline
-await pipeline.ExecuteAsync(async token =>
-{
-    // Your custom logic here
-});
-```
-<!-- endSnippet -->
-
-### Dependency injection
-
-If you prefer to define resilience pipelines using [`IServiceCollection`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection), you'll need to install the [Polly.Extensions](https://www.nuget.org/packages/Polly.Extensions/) package:
-
-```sh
-dotnet add package Polly.Extensions
-```
-
-You can then define your resilience pipeline using the `AddResiliencePipeline(...)` extension method as shown:
-
-<!-- snippet: quick-start-di -->
-```cs
-var services = new ServiceCollection();
-
-// Define a resilience pipeline with the name "my-pipeline"
-services.AddResiliencePipeline("my-pipeline", builder =>
-{
-    builder
-        .AddRetry(new RetryStrategyOptions())
-        .AddTimeout(TimeSpan.FromSeconds(10));
-});
-
-// Build the service provider
-IServiceProvider serviceProvider = services.BuildServiceProvider();
-
-// Retrieve ResiliencePipelineProvider that caches and dynamically creates the resilience pipelines
-var pipelineProvider = serviceProvider.GetRequiredService<ResiliencePipelineProvider<string>>();
-
-// Retrieve resilience pipeline using the name it was registered with
-ResiliencePipeline pipeline = pipelineProvider.GetPipeline("my-pipeline");
-
-// Execute the pipeline
-await pipeline.ExecuteAsync(async token =>
-{
-    // Your custom logic here
-});
-```
-<!-- endSnippet -->
-
 ## Resilience strategies
 
 | Strategy | Reactive | Premise | AKA | How does the strategy mitigate?|
@@ -90,30 +17,41 @@ await pipeline.ExecuteAsync(async token =>
 |[Fallback](strategies/fallback.md)|Yes|Things will still fail - plan what you will do when that happens.| *Degrade gracefully*  |Defines an alternative value to be returned (or action to be executed) on failure. |
 |[Hedging](strategies/hedging.md)|Yes|Things can be slow sometimes, plan what you will do when that happens.| *Hedge your bets*  | Executes parallel actions when things are slow and waits for the fastest one.  |
 
-Visit the [resilience strategies](resilience-strategies.md) section to understand their structure and explore various configuration methods.
-
-## Topics
-
-- [General](general.md): General information about Polly.
-- [Resilience pipelines](resilience-pipelines.md): Understanding the use of resilience pipelines.
-- [Resilience strategies](resilience-strategies.md): General information about resilience strategies and how to configure them.
-- [Resilience context](resilience-context.md): Describes the resilience context used by resilience pipelines and strategies.
-- [Resilience pipeline registry](resilience-pipeline-registry.md): Exploring the registry that stores resilience pipelines.
-- [Dependency injection](dependency-injection.md): How Polly integrates with Dependency Injection.
-- [Telemetry](telemetry.md): Insights into telemetry generated by resilience pipelines and strategies.
-- [Extensibility](v7/extensibility.md): Learn how you can extend Polly with new resilience strategies.
-- [Polly-Contrib](polly-contrib.md): Learn how to contribute to and extend the Polly ecosystem.
-- [Simmy](simmy.md): Get to know chaos engineering via Polly's capabilities.
-- [Third-Party Libraries and Contributions](libraries-and-contributions.md): Find out which libraries Polly depends on and who contributes to its development.
-- [Resources](resources.md): Browse through blogs, podcasts, courses, e-books, and other community resources.
-- [Using Polly with HttpClientFactory](https://github.com/App-vNext/Polly/wiki/Polly-and-HttpClientFactory): For using Polly with HttpClientFactory in ASP.NET Core 2.1 and later versions.
-
-## Topics (previous Polly versions)
+Visit the [resilience strategies](strategies/readme.md) section to understand their structure and explore various configuration methods.
+
+## Next steps
+
+Visit the [getting started](getting-started.md) section and learn how to quickly start using Polly.
+
+## Articles
+
+- [Introduction](readme.md): General information about the project and its goals.
+- [Getting started](getting-started.md): A guide to help you get started with the project.
+- Resilience strategies: A collection of strategies for improving the resilience of your system.
+  - [Timeout](strategies/timeout.md): A strategy for setting a maximum time limit for a request.
+  - [Retry](strategies/retry.md): A strategy for retrying failed requests.
+  - [Rate limiter](strategies/rate-limiter.md): A strategy for limiting the rate of requests.
+  - [Hedging](strategies/hedging.md): A strategy for hedging against long request times.
+  - [Fallback](strategies/fallback.md): A strategy for providing a fallback response in case of failure.
+  - [Circuit breaker](strategies/circuit-breaker.md): A strategy for breaking the circuit when a system is down.
+- Resilience pipelines: Understanding the use of resilience pipelines.
+  - [Resilience pipeline registry](pipelines/resilience-pipeline-registry.md): Exploring the registry that stores resilience pipelines.
+- vanced topics: A collection of advanced topics for further learning.
+  - [Telemetry and monitoring](advanced/telemetry.md): Insights into telemetry generated by resilience pipelines and strategies.
+  - [Chaos engineering](advanced/simmy.md): Get to know chaos engineering via the project's capabilities.
+  - [Dependency injection](advanced/dependency-injection.md): How the project integrates with Dependency Injection.
+- Community and resources: A collection of resources and community contributions.
+  - [Polly-Contrib projects and libraries](community/polly-contrib.md): Learn how to contribute to and extend the project ecosystem.
+  - [Libraries and contributions](community/libraries-and-contributions.md): Find out which libraries the project depends on and who contributes to its development.
+  - [Useful resources and links](community/resources.md): Browse through blogs, podcasts, courses, e-books, and other community resources.
+- [API](api/readme.md): The API documentation for the project.
+
+## Articles (previous Polly versions)
 
 - [Extensibility (v7)](v7/extensibility.md): Learn how you can extend Polly with new policies.
 
 ## Samples
 
-- [Samples](samples/README.md): Samples in this repository that serve as an introduction to Polly.
+- [Samples](https://github.com/App-vNext/Polly/tree/main/samples): Samples in this repository that serve as an introduction to Polly.
 - [Polly-Samples](https://github.com/App-vNext/Polly-Samples): Contains practical examples for using various implementations of Polly. Please feel free to contribute to the Polly-Samples repository in order to assist others who are either learning Polly for the first time, or are seeking advanced examples and novel approaches provided by our generous community.
 - Microsoft's [eShopOnContainers project](https://github.com/dotnet-architecture/eShopOnContainers): Sample project demonstrating a .NET Microservices architecture and using Polly for resilience.
diff --git a/docs/dependency-injection.md → docs/advanced/dependency-injection.md b/docs/dependency-injection.md → docs/advanced/dependency-injection.md
@@ -1,6 +1,6 @@
 # Dependency injection
 
-Starting with version 8, Polly provides features that make the integration of Polly with the .NET [`IServiceCollection`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection) Dependency Injection (DI) container more streamlined. This is a thin layer atop the [resilience pipeline registry](resilience-pipeline-registry.md) which manages resilience pipelines.
+Starting with version 8, Polly provides features that make the integration of Polly with the .NET [`IServiceCollection`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection) Dependency Injection (DI) container more streamlined. This is a thin layer atop the [resilience pipeline registry](../pipelines/resilience-pipeline-registry.md) which manages resilience pipelines.
 
 ## Usage
 
@@ -49,7 +49,8 @@ The `AddResiliencePipeline` extension method also registers the following servic
 - `ResiliencePipelineProvider<string>`: Allows retrieving resilience pipelines.
 - `IOptions<ResiliencePipelineRegistryOptions<string>>`: Options for `ResiliencePipelineRegistry<string>`.
 
-> [!NOTE] The generic `string`` is inferred since the pipeline was defined using the "my-key" value.
+> [!NOTE]
+> The generic `string`` is inferred since the pipeline was defined using the "my-key" value.
 
 If you only need the registry without defining a pipeline, use the `AddResiliencePipelineRegistry(...)` method.
 

diff --git a/docs/extensiblity.md → docs/advanced/extensibility.md b/docs/extensiblity.md → docs/advanced/extensibility.md
diff --git a/docs/resilience-context.md → docs/advanced/resilience-context.md b/docs/resilience-context.md → docs/advanced/resilience-context.md
diff --git a/docs/simmy.md → docs/advanced/simmy.md b/docs/simmy.md → docs/advanced/simmy.md
diff --git a/docs/telemetry.md → docs/advanced/telemetry.md b/docs/telemetry.md → docs/advanced/telemetry.md
diff --git a/docs/libraries-and-contributions.md → .../community/libraries-and-contributions.md b/docs/libraries-and-contributions.md → .../community/libraries-and-contributions.md
diff --git a/docs/polly-contrib.md → docs/community/polly-contrib.md b/docs/polly-contrib.md → docs/community/polly-contrib.md
diff --git a/docs/resources.md → docs/community/resources.md b/docs/resources.md → docs/community/resources.md
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,72 @@
+# Getting started
+
+To use Polly, you must provide a callback and execute it using [**resilience pipeline**](pipelines/readme.md). A resilience pipeline is a combination of one or more [**resilience strategies**](strategies/readme.md) such as retry, timeout, and rate limiter. Polly uses **builders** to integrate these strategies into a pipeline.
+
+To get started, first add the [Polly.Core](https://www.nuget.org/packages/Polly.Core/) package to your project by running the following command:
+
+```sh
+dotnet add package Polly.Core
+```
+
+You can create a `ResiliencePipeline` using the `ResiliencePipelineBuilder` class as shown below:
+
+<!-- snippet: quick-start -->
+```cs
+// Create a instance of builder that exposes various extensions for adding resilience strategies
+var builder = new ResiliencePipelineBuilder();
+
+// Add retry using the default options
+builder.AddRetry(new RetryStrategyOptions());
+
+// Add 10 second timeout
+builder.AddTimeout(TimeSpan.FromSeconds(10));
+
+// Build the resilience pipeline
+ResiliencePipeline pipeline = builder.Build();
+
+// Execute the pipeline
+await pipeline.ExecuteAsync(async token =>
+{
+    // Your custom logic here
+});
+```
+<!-- endSnippet -->
+
+## Dependency injection
+
+If you prefer to define resilience pipelines using [`IServiceCollection`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection), you'll need to install the [Polly.Extensions](https://www.nuget.org/packages/Polly.Extensions/) package:
+
+```sh
+dotnet add package Polly.Extensions
+```
+
+You can then define your resilience pipeline using the `AddResiliencePipeline(...)` extension method as shown:
+
+<!-- snippet: quick-start-di -->
+```cs
+var services = new ServiceCollection();
+
+// Define a resilience pipeline with the name "my-pipeline"
+services.AddResiliencePipeline("my-pipeline", builder =>
+{
+    builder
+        .AddRetry(new RetryStrategyOptions())
+        .AddTimeout(TimeSpan.FromSeconds(10));
+});
+
+// Build the service provider
+IServiceProvider serviceProvider = services.BuildServiceProvider();
+
+// Retrieve ResiliencePipelineProvider that caches and dynamically creates the resilience pipelines
+var pipelineProvider = serviceProvider.GetRequiredService<ResiliencePipelineProvider<string>>();
+
+// Retrieve resilience pipeline using the name it was registered with
+ResiliencePipeline pipeline = pipelineProvider.GetPipeline("my-pipeline");
+
+// Execute the pipeline
+await pipeline.ExecuteAsync(async token =>
+{
+    // Your custom logic here
+});
+```
+<!-- endSnippet -->
diff --git a/docs/resilience-pipelines.md → docs/pipelines/README.md b/docs/resilience-pipelines.md → docs/pipelines/README.md
diff --git a/docs/resilience-pipeline-registry.md → ...pipelines/resilience-pipeline-registry.md b/docs/resilience-pipeline-registry.md → ...pipelines/resilience-pipeline-registry.md
@@ -96,7 +96,7 @@ The constructor for `ResiliencePipelineRegistry<TKey>` accepts a parameter of ty
 | `BuilderNameFormatter`  | Function returning the `key.ToString()` value.                  | Delegate formatting `TKey` to builder name.                       |
 
 > [>NOTE]
-> The `BuilderName` and `InstanceName` are used in [telemetry](telemetry.md#metrics).
+> The `BuilderName` and `InstanceName` are used in [telemetry](../advanced/telemetry.md#metrics).
 
 Usage example:
 
@@ -197,8 +197,8 @@ registry.TryAddBuilder("A", (builder, context) =>
 ```
 <!-- endSnippet -->
 
-Both `AddReloadToken(...)` and `OnPipelineDisposed(...)` are used to implement the `EnableReloads<TOptions>(...)` extension method that is used by the [Dependency Injection layer](dependency-injection.md#dynamic-reloads).
+Both `AddReloadToken(...)` and `OnPipelineDisposed(...)` are used to implement the `EnableReloads<TOptions>(...)` extension method that is used by the [Dependency Injection layer](../advanced/dependency-injection.md#dynamic-reloads).
 
 ## Complex registry keys
 
-Though the pipeline registry supports complex keys, we suggest you use them when defining pipelines with the [Dependency Injection](dependency-injection.md) (DI) containers. For further information, see the [section on complex pipeline keys](dependency-injection.md#complex-pipeline-keys).
+Though the pipeline registry supports complex keys, we suggest you use them when defining pipelines with the [Dependency Injection](../advanced/dependency-injection.md) (DI) containers. For further information, see the [section on complex pipeline keys](../advanced/dependency-injection.md#complex-pipeline-keys).
diff --git a/docs/resilience-strategies.md → docs/strategies/README.md b/docs/resilience-strategies.md → docs/strategies/README.md