Merge pull request #1755 from ThreeMammals/release/20.0

Documentation release 20.0.1
--------------------------------

Guillaume Gnaegi (1):
      #1731 Read the Docs configuration file v2 (#1733)

Raman Maksimchuk (1):
      #1731 Docs for 20.0 release (#1754)

raman-m (2):
      Prepare for the 20.0.1 release
      Trigger new build...

Author: raman-m

.readthedocs.yaml

@@ -0,0 +1,31 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+   - pdf
+   - epub
+
+# Optional but recommended, declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

Ocelot.sln

@@ -10,6 +10,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 		.dockerignore = .dockerignore
 		.editorconfig = .editorconfig
 		.gitignore = .gitignore
+		.readthedocs.yaml = .readthedocs.yaml
 		build.cake = build.cake
 		build.ps1 = build.ps1
 		codeanalysis.ruleset = codeanalysis.ruleset

README.md

@@ -2,16 +2,16 @@
 
 [![CircleCI](https://circleci.com/gh/ThreeMammals/Ocelot/tree/main.svg?style=svg)](https://circleci.com/gh/ThreeMammals/Ocelot/tree/main)
 
-[![Coverage Status](https://coveralls.io/repos/github/ThreeMammals/Ocelot/badge.svg)](https://coveralls.io/github/ThreeMammals/Ocelot)
+<!-- [![Coverage Status](https://coveralls.io/repos/github/ThreeMammals/Ocelot/badge.svg)](https://coveralls.io/github/ThreeMammals/Ocelot) -->
 
-# Ocelot
+## About
 
 Ocelot is a .NET API Gateway. This project is aimed at people using .NET running a microservices / service-oriented architecture 
-that need a unified point of entry into their system. However it will work with anything that speaks HTTP and run on any platform that ASP.NET Core supports.
+that need a unified point of entry into their system. However it will work with anything that speaks HTTP(S) and run on any platform that ASP.NET Core supports.
 
-In particular I want easy integration with IdentityServer reference and bearer tokens. 
-
-We have been unable to find this in my current workplace without having to write our own Javascript middlewares to handle the IdentityServer reference tokens. We would rather use the IdentityServer code that already exists to do this.
+In particular we want easy integration with [IdentityServer](https://github.com/IdentityServer) reference and [Bearer](https://oauth.net/2/bearer-tokens/) tokens. 
+We have been unable to find this in our current workplace without having to write our own Javascript middlewares to handle the IdentityServer reference tokens.
+We would rather use the IdentityServer code that already exists to do this.
 
 Ocelot is a bunch of middlewares in a specific order.
 
@@ -23,56 +23,74 @@ That is basically it with a bunch of other features!
 
 ## Features
 
-A quick list of Ocelot's capabilities for more information see the [documentation](https://ocelot.readthedocs.io/en/latest/).
-
-* Routing
-* Request Aggregation
-* Service Discovery with Consul & Eureka
-* Service Fabric
-* Kubernetes 
-* WebSockets
-* Authentication
-* Authorization
-* Rate Limiting
-* Caching
-* Retry policies / QoS
-* Load Balancing
-* Logging / Tracing / Correlation
-* Headers / Method / Query String / Claims Transformation
-* Custom Middleware / Delegating Handlers
-* Configuration / Administration REST API
-* Platform / Cloud Agnostic
+A quick list of Ocelot's capabilities, for more information see the [Documentation](#documentation).
+
+* [Routing](https://ocelot.readthedocs.io/en/latest/features/routing.html)
+* [Request Aggregation](https://ocelot.readthedocs.io/en/latest/features/requestaggregation.html)
+* [GraphQL](https://ocelot.readthedocs.io/en/latest/features/graphql.html) [^1]
+* [Service Discovery](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html) [^2]
+* [Service Fabric](https://ocelot.readthedocs.io/en/latest/features/servicefabric.html)
+* [Kubernetes](https://ocelot.readthedocs.io/en/latest/features/kubernetes.html)
+* [Websockets](https://ocelot.readthedocs.io/en/latest/features/websockets.html)
+* [Authentication](https://ocelot.readthedocs.io/en/latest/features/authentication.html)
+* [Authorization](https://ocelot.readthedocs.io/en/latest/features/authorization.html)
+* [Rate Limiting](https://ocelot.readthedocs.io/en/latest/features/ratelimiting.html)
+* [Caching](https://ocelot.readthedocs.io/en/latest/features/caching.html)
+* [Quality of Service](https://ocelot.readthedocs.io/en/latest/features/qualityofservice.html) [^3]
+* [Load Balancer](https://ocelot.readthedocs.io/en/latest/features/loadbalancer.html)
+* [Logging](https://ocelot.readthedocs.io/en/latest/features/logging.html) / [Tracing](https://ocelot.readthedocs.io/en/latest/features/tracing.html) / [Correlation](https://ocelot.readthedocs.io/en/latest/features/requestid.html)
+* [Headers](https://ocelot.readthedocs.io/en/latest/features/headerstransformation.html) / [Method](https://ocelot.readthedocs.io/en/latest/features/methodtransformation.html) / [Query String](https://ocelot.readthedocs.io/en/latest/search.html?q=Query+String&check_keywords=yes&area=default) / [Claims](https://ocelot.readthedocs.io/en/latest/features/claimstransformation.html) Transformation
+* [Custom Middleware](https://ocelot.readthedocs.io/en/latest/features/middlewareinjection.html) / [Delegating Handlers](https://ocelot.readthedocs.io/en/latest/features/delegatinghandlers.html)
+* [Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html) / [Administration](https://ocelot.readthedocs.io/en/latest/features/administration.html) REST API
+* [Platform](https://ocelot.readthedocs.io/en/latest/building/building.html?highlight=Platform#building) & Cloud Agnostic [Building](https://ocelot.readthedocs.io/en/latest/building/building.html)
 
 ## Install
 
-Ocelot is designed to work with ASP.NET and it targets `net7.0`.
-
-Install Ocelot and its dependencies using NuGet Package Manager:
+Ocelot is designed to work with ASP.NET Core and it targets `net7.0` framework.
+Install [Ocelot package](https://www.nuget.org/packages/Ocelot) and its dependencies using NuGet Package Manager:
 ```powershell
 Install-Package Ocelot
 ```
-
 Or via the .NET CLI:
 ```shell
 dotnet add package Ocelot
 ```
-
-All versions can be found [here](https://www.nuget.org/packages/Ocelot/).
+All versions can be found [on nuget](https://www.nuget.org/packages/Ocelot#versions-body-tab).
 
 ## Documentation
-
-Please click [here](https://ocelot.readthedocs.io/en/latest/) for the Ocelot documentation. This includes lots of information and will be helpful if you want to understand the features Ocelot currently offers.
+- [Ocelot documentation — Read the Docs](https://ocelot.readthedocs.io)
+  <br/>This includes lots of information and will be helpful if you want to understand the features Ocelot currently offers.
+- [Ocelot RST Docs](https://github.com/ThreeMammals/Ocelot/tree/develop/docs)
+  <br/>This includes source code of documentation as **.rst** files which are up to date for current development.
 
 ## Coming up
-
-You can see what we are working on [here](https://github.com/ThreeMammals/Ocelot/issues).
+You can see what we are working on in [backlog](https://github.com/ThreeMammals/Ocelot/issues).
 
 ## Contributing
 
-We love to receive contributions from the community so please keep them coming :) 
-
-Pull requests, issues and commentary welcome!
-
-Please complete the relevant template for issues and PRs. Sometimes it's worth getting in touch with us to discuss changes before doing any work in case this is something we are already doing or it might not make sense. We can also give advice on the easiest way to do things :)
-
-Finally we mark all existing issues as help wanted, small, medium and large effort. If you want to contribute for the first time I suggest looking at a help wanted & small effort issue :)
+We love to receive contributions from the community, so please keep them coming :octocat: 
+<br/>Pull requests, issues and commentary welcome!
+
+Please complete the relevant [template](https://github.com/ThreeMammals/Ocelot/tree/main/.github) for [issues](https://github.com/ThreeMammals/Ocelot/blob/main/.github/ISSUE_TEMPLATE.md) and [PRs](https://github.com/ThreeMammals/Ocelot/blob/main/.github/PULL_REQUEST_TEMPLATE.md).
+Sometimes it's worth getting in touch with us to [discuss](https://github.com/ThreeMammals/Ocelot/discussions) changes before doing any work in case this is something we are already doing or it might not make sense.
+We can also give advice on the easiest way to do things :octocat: 
+
+Finally, we mark all existing issues as [![label: help wanted][~helpwanted]](https://github.com/ThreeMammals/Ocelot/labels/help%20wanted)
+[![label: small effort][~smalleffort]](https://github.com/ThreeMammals/Ocelot/labels/small%20effort)
+[![label: medium effort][~mediumeffort]](https://github.com/ThreeMammals/Ocelot/labels/medium%20effort)
+[![label: large effort][~largeeffort]](https://github.com/ThreeMammals/Ocelot/labels/large%20effort) [^4].
+<br/>If you want to contribute for the first time, we suggest looking at a [![label: help wanted][~helpwanted]](https://github.com/ThreeMammals/Ocelot/labels/help%20wanted) 
+[![label: small effort][~smalleffort]](https://github.com/ThreeMammals/Ocelot/labels/small%20effort) 
+[![label: good first issue][~goodfirstissue]](https://github.com/ThreeMammals/Ocelot/labels/good%20first%20issue) :octocat: 
+
+[~helpwanted]: https://img.shields.io/badge/-help%20wanted-128A0C.svg
+[~smalleffort]: https://img.shields.io/badge/-small%20effort-fef2c0.svg
+[~mediumeffort]: https://img.shields.io/badge/-medium%20effort-e0f42c.svg
+[~largeeffort]: https://img.shields.io/badge/-large%20effort-10526b.svg
+[~goodfirstissue]: https://img.shields.io/badge/-good%20first%20issue-ffc4d8.svg
+
+### Notes
+[^1]: Ocelot doesn’t directly support [GraphQL](https://graphql.org/). Developers can easily integrate the [GraphQL for .NET](/graphql-dotnet/graphql-dotnet) library.
+[^2]: Ocelot does support [Consul](https://www.consul.io/), [Netflix Eureka](https://www.nuget.org/packages/Steeltoe.Discovery.Eureka), [Service Fabric](https://azure.microsoft.com/en-us/products/service-fabric/) service discovery providers, and special modes like [Dynamic Routing](/ThreeMammals/Ocelot/blob/main/docs/features/servicediscovery.rst#dynamic-routing) and [Custom Providers](/ThreeMammals/Ocelot/blob/main/docs/features/servicediscovery.rst#custom-providers).
+[^3]: Retry policies only via [Polly](/App-vNext/Polly) library.
+[^4]: See all [labels](https://github.com/ThreeMammals/Ocelot/issues/labels) of the repository.

ReleaseNotes.md

@@ -1,2 +1,2 @@
-## September 2023 (version {0}) aka [Polish Apple](https://www.google.com/search?q=Polish+Apple) release
-> Codenamed as **[Polish Apple](https://www.google.com/search?q=Polish+Apple)**
+## Documentation release {0} for [Polish Apple](https://www.google.com/search?q=Polish+Apple), v{1}
+Special thanks to @ggnaegi!

build.cake

@@ -85,8 +85,8 @@ Task("Release")
 	.IsDependentOn("Build")
 	.IsDependentOn("CreateReleaseNotes")
 	.IsDependentOn("CreateArtifacts")
-	.IsDependentOn("PublishGitHubRelease")
-    .IsDependentOn("PublishToNuget");
+	.IsDependentOn("PublishGitHubRelease");
+    // .IsDependentOn("PublishToNuget");
 
 Task("Compile")
 	.IsDependentOn("Clean")
@@ -138,11 +138,6 @@ Task("CreateReleaseNotes")
 	{	
 		Information($"Generating release notes at {releaseNotesFile}");
 
-		var releaseVersion = versioning.NuGetVersion;
-		// Read main header from Git file, substitute version in header, and add content further...
-		var releaseHeader = string.Format(System.IO.File.ReadAllText("./ReleaseNotes.md"), releaseVersion);
-		var releaseNotes = new List<string> { releaseHeader };
-
 		// local helper function
 		Func<string, IEnumerable<string>> GitHelper = (command) =>
 		{
@@ -160,6 +155,11 @@ Task("CreateReleaseNotes")
 		var lastRelease = lastReleaseTags.First(t => !t.StartsWith("net")); // skip 'net*-vX.Y.Z' tag and take 'major.minor.build'
 		Information("Last release tag is " + lastRelease);
 
+		var releaseVersion = versioning.NuGetVersion;
+		// Read main header from Git file, substitute version in header, and add content further...
+		var releaseHeader = string.Format(System.IO.File.ReadAllText("./ReleaseNotes.md"), releaseVersion, lastRelease);
+		var releaseNotes = new List<string> { releaseHeader };
+
 		var shortlogSummary = GitHelper($"shortlog --no-merges --numbered --summary {lastRelease}..HEAD");
 		var re = new Regex(@"^[\s\t]*(?'commits'\d+)[\s\t]+(?'author'.*)$");
 		var summary = shortlogSummary
@@ -296,9 +296,9 @@ Task("CreateReleaseNotes")
 				}
 			}
 		} // END of Top 3
-		releaseNotes.Add("### Honoring :medal_sports: aka Top Contributors :clap:");
-		releaseNotes.AddRange(topContributors);
-		releaseNotes.Add("");
+		//releaseNotes.Add("### Honoring :medal_sports: aka Top Contributors :clap:");
+		//releaseNotes.AddRange(topContributors);
+		//releaseNotes.Add("");
 		releaseNotes.Add("### Starring :star: aka Release Influencers :bowtie:");
 		releaseNotes.AddRange(starring);
 		releaseNotes.Add("");
@@ -409,26 +409,31 @@ Task("CreateArtifacts")
 	{
 		EnsureDirectoryExists(packagesDir);
 
-		CopyFiles("./src/**/Release/Ocelot.*.nupkg", packagesDir);
+		System.IO.File.AppendAllLines(artifactsFile, new[] { "ReleaseNotes.md" });
+		CopyFiles("./ReleaseNotes.md", packagesDir);
 
-		var projectFiles = GetFiles("./src/**/Release/Ocelot.*.nupkg");
-
-		foreach(var projectFile in projectFiles)
-		{
-			System.IO.File.AppendAllLines(
-				artifactsFile,
-				new[] { projectFile.GetFilename().FullPath, "ReleaseNotes.md" }
-			);
-		}
+		// CopyFiles("./src/**/Release/Ocelot.*.nupkg", packagesDir);
+		// var projectFiles = GetFiles("./src/**/Release/Ocelot.*.nupkg");
+		// foreach(var projectFile in projectFiles)
+		// {
+		// 	System.IO.File.AppendAllLines(
+		// 		artifactsFile,
+		// 		new[] { projectFile.GetFilename().FullPath }
+		// 	);
+		// }
 
 		var artifacts = System.IO.File.ReadAllLines(artifactsFile)
 			.Distinct();
 
 		foreach(var artifact in artifacts)
 		{
 			var codePackage = packagesDir + File(artifact);
-
-			Information("Created package " + codePackage);
+			if (FileExists(codePackage))
+			{
+				Information("Created package " + codePackage);
+			} else {
+				Information("Package does not exist: " + codePackage);
+			}
 		}
 	});
 
@@ -586,14 +591,12 @@ private void CreateGitHubRelease()
 
 	var content = new System.Net.Http.StringContent(json, System.Text.Encoding.UTF8, "application/json");
 
-	using(var client = new System.Net.Http.HttpClient())
+	using (var client = new System.Net.Http.HttpClient())
 	{	
-			client.DefaultRequestHeaders.Authorization = 
-    new System.Net.Http.Headers.AuthenticationHeaderValue(
-        "Basic", Convert.ToBase64String(
-            System.Text.ASCIIEncoding.ASCII.GetBytes(
-               $"{gitHubUsername}:{gitHubPassword}")));
-
+		client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
+        	"Basic",
+			Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes($"{gitHubUsername}:{gitHubPassword}"))
+		);
 		client.DefaultRequestHeaders.Add("User-Agent", "Ocelot Release");
 
 		var result = client.PostAsync("https://api.github.com/repos/ThreeMammals/Ocelot/releases", content).Result;
@@ -618,14 +621,12 @@ private void UploadFileToGitHubRelease(FilePath file)
 	var content = new System.Net.Http.ByteArrayContent(data);
 	content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/octet-stream");
 
-	using(var client = new System.Net.Http.HttpClient())
+	using (var client = new System.Net.Http.HttpClient())
 	{	
-			client.DefaultRequestHeaders.Authorization = 
-    new System.Net.Http.Headers.AuthenticationHeaderValue(
-        "Basic", Convert.ToBase64String(
-            System.Text.ASCIIEncoding.ASCII.GetBytes(
-               $"{gitHubUsername}:{gitHubPassword}")));
-
+		client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
+        	"Basic",
+			Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes($"{gitHubUsername}:{gitHubPassword}"))
+		);
 		client.DefaultRequestHeaders.Add("User-Agent", "Ocelot Release");
 
 		var result = client.PostAsync($"https://uploads.github.com/repos/ThreeMammals/Ocelot/releases/{releaseId}/assets?name={file.GetFilename()}", content).Result;
@@ -642,25 +643,22 @@ private void CompleteGitHubRelease()
 	var request = new System.Net.Http.HttpRequestMessage(new System.Net.Http.HttpMethod("Patch"), $"https://api.github.com/repos/ThreeMammals/Ocelot/releases/{releaseId}");
 	request.Content = new System.Net.Http.StringContent(json, System.Text.Encoding.UTF8, "application/json");
 
-	using(var client = new System.Net.Http.HttpClient())
+	using (var client = new System.Net.Http.HttpClient())
 	{	
-			client.DefaultRequestHeaders.Authorization = 
-    new System.Net.Http.Headers.AuthenticationHeaderValue(
-        "Basic", Convert.ToBase64String(
-            System.Text.ASCIIEncoding.ASCII.GetBytes(
-               $"{gitHubUsername}:{gitHubPassword}")));
-
+		client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
+        	"Basic",
+			Convert.ToBase64String(System.Text.ASCIIEncoding.ASCII.GetBytes($"{gitHubUsername}:{gitHubPassword}"))
+		);
 		client.DefaultRequestHeaders.Add("User-Agent", "Ocelot Release");
 
 		var result = client.SendAsync(request).Result;
-		if(result.StatusCode != System.Net.HttpStatusCode.OK) 
+		if (result.StatusCode != System.Net.HttpStatusCode.OK) 
 		{
 			throw new Exception("CompleteGitHubRelease result.StatusCode = " + result.StatusCode);
 		}
 	}
 }
 
-
 /// gets the resource from the specified url
 private async Task<string> GetResourceAsync(string url)
 {