Follow up #2286 Release v24.0 | Artifacts and bug fixing

Author: raman-m

README.md

@@ -1,13 +1,16 @@
-![Ocelot Logo](https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/ocelot_logo.png)
+![Ocelot Logo](https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/ocelot_logo.png)
 
 [![Release Status](https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml/badge.svg)](https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml)
 [![Development Status](https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml/badge.svg)](https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml)
-[![ReadTheDocs Status](https://readthedocs.org/projects/ocelot/badge/?version=latest&style=flat-square)](https://app.readthedocs.org/projects/ocelot/builds/?version__slug=latest)
-[![Coveralls Status](https://coveralls.io/repos/github/ThreeMammals/Ocelot/badge.svg?branch=main)](https://coveralls.io/github/ThreeMammals/Ocelot?branch=main)
+[![ReadTheDocs](https://readthedocs.org/projects/ocelot/badge/?version=latest&style=flat-square)](https://app.readthedocs.org/projects/ocelot/builds/?version__slug=latest)
+[![Coveralls](https://coveralls.io/repos/github/ThreeMammals/Ocelot/badge.svg?branch=main)](https://coveralls.io/github/ThreeMammals/Ocelot?branch=main)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ThreeMammals/Ocelot/blob/main/LICENSE.md)
 [![NuGet](https://img.shields.io/nuget/v/Ocelot?logo=nuget&label=NuGet&color=blue)](https://www.nuget.org/packages/Ocelot/ "Download Ocelot from NuGet.org")
 [![Downloads](https://img.shields.io/nuget/dt/Ocelot?logo=nuget&label=Downloads)](https://www.nuget.org/packages/Ocelot/ "Total Ocelot downloads from NuGet.org")
 
+[~docspassing]: https://img.shields.io/badge/Docs-passing-44CC11?style=flat-square
+[~docsfailing]: https://img.shields.io/badge/Docs-failing-red?style=flat-square
+
 ## About
 Ocelot is a .NET [API gateway](https://www.bing.com/search?q=API+gateway).
 This project is aimed at people using .NET running a microservices (service-oriented) architecture that needs a unified point of entry into their system.
@@ -64,30 +67,32 @@ All versions are available [on NuGet](https://www.nuget.org/packages/Ocelot#vers
 
 ## Documentation
 - [RST-sources](https://github.com/ThreeMammals/Ocelot/tree/develop/docs):
-  This includes the source code of the documentation as **.rst**-files, which are up to date for current development.
+  This includes the source code for the documentation (in reStructuredText format, .rst files), which is up to date for the current [development](https://github.com/ThreeMammals/Ocelot/tree/develop/).
+  And the rendered HTML documentation is available [here](https://ocelot.readthedocs.io/en/develop/).
 - [Read the Docs](https://ocelot.readthedocs.io):
-  This includes a lot of information and will be helpful if you want to understand the features Ocelot currently offers.
+  This official website, in HTML format, contains a wealth of information and will be helpful if you want to understand the [features](#features) that Ocelot currently offers.
+  The rendered HTML documentation, which is currently in [development](https://github.com/ThreeMammals/Ocelot/tree/develop/docs), is available [here](https://ocelot.readthedocs.io/en/develop/).
 - [Ask Ocelot Guru](https://gurubase.io/g/ocelot):
-  It is an Ocelot-focused AI designed to answer your questions. [^5]
+  It is an AI focused on Ocelot, designed to answer your questions. [^5]
 
 ## Coming up
 You can see what we are working on in the [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! <img src="https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/octocat.png" alt="octocat" height="20" />
+Pull requests, issues, and commentary welcome! <img src="https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/octocat.png" alt="octocat" height="25" />
 
 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 [pull requests](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 <img src="https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/octocat.png" alt="octocat" height="20" />
+We can also give advice on the easiest way to do things <img src="https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/octocat.png" alt="octocat" height="25" />
 
 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). [^6]
 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) <img src="https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/octocat.png" alt="octocat" height="20" />
+[![label: good first issue][~goodfirstissue]](https://github.com/ThreeMammals/Ocelot/labels/good%20first%20issue) <img src="https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/octocat.png" alt="octocat" height="25" />
 
 [~helpwanted]: https://img.shields.io/badge/-help%20wanted-128A0C.svg
 [~smalleffort]: https://img.shields.io/badge/-small%20effort-fef2c0.svg

build.cake

@@ -92,6 +92,7 @@ Task("Compile")
 	.IsDependentOn("Version")
 	.Does(() =>
 	{	
+		PreprocessReadMe();
 		Information("Branch: " + GetBranchName());
 		Information("Build: " + compileConfig);
 		Information("Solution: " + slnFile);
@@ -181,7 +182,7 @@ Task("CreateReleaseNotes")
         // Read main header from Git file, substitute version in header, and add content further...
         Information("{0}  New release tag is " + releaseVersion);
         Information("{1} Last release tag is " + lastRelease);
-        var body = System.IO.File.ReadAllText("./ReleaseNotes.md");
+        var body = System.IO.File.ReadAllText("./ReleaseNotes.md", System.Text.Encoding.UTF8);
         var releaseHeader = string.Format(body, releaseVersion, lastRelease);
         releaseNotes = new List<string> { releaseHeader };
         if (IsTechnicalRelease)
@@ -466,7 +467,7 @@ private void WriteReleaseNotes()
 	var content = System.IO.File.ReadAllText(releaseNotesFile, Encoding.UTF8);
 	if (string.IsNullOrEmpty(content))
 	{
-		System.IO.File.WriteAllText(releaseNotesFile, "No commits since last release");
+		System.IO.File.WriteAllText(releaseNotesFile, "No commits since last release", System.Text.Encoding.UTF8);
 	}
 	Information("Release notes are >>>{0}<<<", NL + content);
 }
@@ -654,7 +655,7 @@ Task("PublishGitHubRelease")
 		if (!IsRunningInCICD())
 		{
 			Warning("We are not running on the CI/CD so we won't publish a GitHub release");
-			return;
+			//return;
 		}
 
 		dynamic release = CreateGitHubRelease();
@@ -717,24 +718,60 @@ Task("PublishToNuget")
 			Information("Skipping of publishing to NuGet because of technical release...");
 			return;
 		}
-
-		if (IsRunningInCICD())
-		{
-			var nugetFeedStableKey = EnvironmentVariable("OCELOT_NUGET_API_KEY_2025");
-			var nugetFeedStableUploadUrl = "https://www.nuget.org/api/v2/package";
-			var nugetFeedStableSymbolsUploadUrl = "https://www.nuget.org/api/v2/package";
-			PublishPackages(packagesDir, artifactsFile, nugetFeedStableKey, nugetFeedStableUploadUrl, nugetFeedStableSymbolsUploadUrl);
-		}
-		else
+		if (!IsRunningInCICD())
 		{
 			Warning("We are not running on the CI/CD so we won't publish NuGet packages.");
+			//return;
 		}
+		var nugetFeedStableKey = EnvironmentVariable("OCELOT_NUGET_API_KEY_2025");
+		var nugetFeedStableUploadUrl = "https://www.nuget.org/api/v2/package";
+		var nugetFeedStableSymbolsUploadUrl = "https://www.nuget.org/api/v2/package";
+		PublishPackages(packagesDir, artifactsFile, nugetFeedStableKey, nugetFeedStableUploadUrl, nugetFeedStableSymbolsUploadUrl);
 	});
 
 Task("Void").Does(() => {});
 
 RunTarget(target);
 
+private void PreprocessReadMe()
+{
+	const string READMEmd = "./README.md";
+	const string RTD_NuGet_Valid_Domain = "[ReadTheDocs][~docspassing]";
+	const string RTD_Version_Latest  = "[ReadTheDocs](https://readthedocs.org/projects/ocelot/badge/?version=latest&style=flat-square)";
+	const string RTD_Version_Develop = "[ReadTheDocs](https://readthedocs.org/projects/ocelot/badge/?version=develop&style=flat-square)";
+	Information($"Processing {READMEmd} ...");
+    var body = System.IO.File.ReadAllText(READMEmd, System.Text.Encoding.UTF8);
+	var RTD_IsReplaced = false;
+	if (body.Contains(RTD_Version_Latest))
+	{
+		Information($"  {READMEmd}: Detected ReadTheDocs LATEST version marker -> {RTD_Version_Latest}");
+		body = body.Replace(RTD_Version_Latest, RTD_NuGet_Valid_Domain);
+		RTD_IsReplaced = true;
+	}
+	if (body.Contains(RTD_Version_Develop))
+	{
+		Information($"  {READMEmd}: Detected ReadTheDocs DEVELOP version marker -> {RTD_Version_Develop}");
+		body = body.Replace(RTD_Version_Develop, RTD_NuGet_Valid_Domain);
+		RTD_IsReplaced = true;
+	}
+	if (RTD_IsReplaced)
+	{
+		Information($"  {READMEmd}: ReadTheDocs badge has been replaced with -> {RTD_NuGet_Valid_Domain}");
+	}	
+
+	const string IMG_Octocat_HTML = "<img src=\"https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/octocat.png\" alt=\"octocat\" height=\"25\" />";
+	const string IMG_NuGet_Valid_MD = "![octocat](https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/octocat-25px.png)";
+	if (body.Contains(IMG_Octocat_HTML))
+	{
+		Information($"  {READMEmd}: Detected Octocat HTML IMG-tag -> " + IMG_Octocat_HTML);
+		body = body.Replace(IMG_Octocat_HTML, IMG_NuGet_Valid_MD);
+		Information($"  {READMEmd}: Octocat HTML IMG-tag has been replaced with -> " + IMG_NuGet_Valid_MD);
+	}
+	Information($"  {READMEmd}: Writing the body of the {READMEmd}...");
+	System.IO.File.WriteAllText(READMEmd, body, System.Text.Encoding.UTF8);
+	Information($"DONE Processing {READMEmd}{NL}");
+}
+
 private void GenerateReport(Cake.Core.IO.FilePath coverageSummaryFile)
 {
 	var dir = System.IO.Directory.GetCurrentDirectory();
@@ -772,17 +809,17 @@ private void PersistVersion(string committedVersion, string newVersion)
 		var file = projectFile.ToString();
 		Information(string.Format("Updating {0}...", file));
 
-		var updatedProjectFile = System.IO.File.ReadAllText(file)
+		var updatedProjectFile = System.IO.File.ReadAllText(file, System.Text.Encoding.UTF8)
 			.Replace(committedVersion, newVersion);
 
-		System.IO.File.WriteAllText(file, updatedProjectFile);
+		System.IO.File.WriteAllText(file, updatedProjectFile, System.Text.Encoding.UTF8);
 	}
 }
 
 /// Publishes code and symbols packages to nuget feed, based on contents of artifacts file
 private void PublishPackages(ConvertableDirectoryPath packagesDir, ConvertableFilePath artifactsFile, string feedApiKey, string codeFeedUrl, string symbolFeedUrl)
 {
-		Information("PublishPackages: Publishing to NuGet...");
+		Information($"{nameof(PublishPackages)}: Publishing to NuGet...");
         var artifacts = System.IO.File
             .ReadAllLines(artifactsFile)
 			.Distinct();
@@ -794,17 +831,30 @@ private void PublishPackages(ConvertableDirectoryPath packagesDir, ConvertableFi
             // "Ocelot.Tracing.Butterfly",
             // "Ocelot.Tracing.OpenTracing",
         };
+		var errors = new List<string>();
 		foreach (var artifact in artifacts)
 		{
             if (skippable.Exists(x => artifact.StartsWith(x)))
 				continue;
 
 			var codePackage = packagesDir + File(artifact);
-			Information("PublishPackages: Pushing package " + codePackage + "...");
-			DotNetNuGetPush(
-				codePackage,
-				new DotNetNuGetPushSettings { ApiKey = feedApiKey, Source = codeFeedUrl }
-			);
+			Information($"{nameof(PublishPackages)}: Pushing package " + codePackage + "...");
+			try
+			{
+				DotNetNuGetPush(codePackage,
+					new DotNetNuGetPushSettings { ApiKey = feedApiKey, Source = codeFeedUrl });
+			}
+			catch (Exception e)
+			{
+				errors.Add(e.Message);
+			}
+		}
+		if (errors.Count > 0)
+		{
+			Information($"{nameof(PublishPackages)}: Errors >>>");
+			var err = string.Join(NL, errors);
+			Warning(err);
+			throw new Exception(err);
 		}
 }
 
@@ -819,7 +869,7 @@ private void SetupGitHubClient(System.Net.Http.HttpClient client)
 
 private dynamic CreateGitHubRelease()
 {
-	var json = $"{{ \"tag_name\": \"{versioning.SemVer}\", \"target_commitish\": \"main\", \"name\": \"{versioning.SemVer}\", \"body\": \"{ReleaseNotesAsJson()}\", \"draft\": true, \"prerelease\": true, \"generate_release_notes\": false }}";
+	var json = $"{{ \"tag_name\": \"{versioning.SemVer}\", \"target_commitish\": \"{versioning.BranchName}\", \"name\": \"{versioning.SemVer}\", \"body\": \"{ReleaseNotesAsJson()}\", \"draft\": true, \"prerelease\": true, \"generate_release_notes\": false }}";
 	var content = new System.Net.Http.StringContent(json, System.Text.Encoding.UTF8, "application/json");
 
 	using (var client = new System.Net.Http.HttpClient())
@@ -841,7 +891,8 @@ private dynamic CreateGitHubRelease()
 
 private string ReleaseNotesAsJson()
 {
-	return System.Text.Encodings.Web.JavaScriptEncoder.Default.Encode(System.IO.File.ReadAllText(releaseNotesFile));
+	var body = System.IO.File.ReadAllText(releaseNotesFile, System.Text.Encoding.UTF8);
+	return System.Text.Encodings.Web.JavaScriptEncoder.Default.Encode(body);
 }
 
 private void UploadFileToGitHubRelease(dynamic release, FilePath file)
@@ -873,7 +924,7 @@ private void CompleteGitHubRelease(dynamic release)
 {
 	int releaseId = release.id;
 	string url = release.url.ToString();
-	var json = $"{{ \"tag_name\": \"{versioning.SemVer}\", \"target_commitish\": \"main\", \"name\": \"{versioning.SemVer}\", \"body\": \"{ReleaseNotesAsJson()}\", \"draft\": false, \"prerelease\": false }}";
+	var json = $"{{ \"tag_name\": \"{versioning.SemVer}\", \"target_commitish\": \"{versioning.BranchName}\", \"name\": \"{versioning.SemVer}\", \"body\": \"{ReleaseNotesAsJson()}\", \"draft\": false, \"prerelease\": false }}";
 	var request = new System.Net.Http.HttpRequestMessage(new System.Net.Http.HttpMethod("Patch"), url); // $"https://api.github.com/repos/ThreeMammals/Ocelot/releases/{releaseId}");
 	request.Content = new System.Net.Http.StringContent(json, System.Text.Encoding.UTF8, "application/json");
 

docs/_static/overrides.css

@@ -4,3 +4,15 @@ blockquote {
 aside.footnote-list {
     font-size: 0.9em;
 }
+.img-valign-middle
+{
+    vertical-align: middle;
+}
+.img-valign-bottom
+{
+    vertical-align: bottom;
+}
+.img-valign-textbottom
+{
+    vertical-align: text-bottom;
+}

docs/building/building.rst

@@ -1,3 +1,7 @@
+.. role:: htm(raw)
+  :format: html
+.. role:: pdf(raw)
+  :format: latex pdflatex
 .. _Ocelot: https://github.com/ThreeMammals/Ocelot
 .. _Cake: https://cakebuild.net
 .. _Bash: https://www.gnu.org/software/bash
@@ -114,22 +118,26 @@ You may need to adjust the platform flag depending on your system.
 With CI/CD
 ----------
 .. _workflows: https://github.com/ThreeMammals/Ocelot/tree/main/.github/workflows 
-.. _PR: https://github.com/ThreeMammals/Ocelot/blob/main/.github/workflows/pr.yml
-.. _Develop: https://github.com/ThreeMammals/Ocelot/blob/main/.github/workflows/develop.yml
-.. _Release: https://github.com/ThreeMammals/Ocelot/blob/main/.github/workflows/release.yml
+.. _PR: https://github.com/ThreeMammals/Ocelot/actions/workflows/pr.yml
+.. _Develop: https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml
+.. _Release: https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml
 .. _Coveralls: https://coveralls.io
 .. |ReleaseButton| image:: https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml/badge.svg
-   :target: https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml
-   :alt: Release Status
+  :target: https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml
+  :alt: Release Status
+  :class: img-valign-textbottom
 .. |DevelopButton| image:: https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml/badge.svg
-   :target: https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml
-   :alt: Development Status
+  :target: https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml
+  :alt: Development Status
+  :class: img-valign-textbottom
 .. |DevelopCoveralls| image:: https://coveralls.io/repos/github/ThreeMammals/Ocelot/badge.svg?branch=develop
-   :target: https://coveralls.io/github/ThreeMammals/Ocelot?branch=develop
-   :alt: Coveralls Status
+  :target: https://coveralls.io/github/ThreeMammals/Ocelot?branch=develop
+  :alt: Coveralls Status
+  :class: img-valign-textbottom
 .. |ReleaseCoveralls| image:: https://coveralls.io/repos/github/ThreeMammals/Ocelot/badge.svg?branch=main
-   :target: https://coveralls.io/github/ThreeMammals/Ocelot?branch=main
-   :alt: Coveralls Status
+  :target: https://coveralls.io/github/ThreeMammals/Ocelot?branch=main
+  :alt: Coveralls Status
+  :class: img-valign-textbottom
 .. _break2: http://break.do
 
   | Folder: ./.github/`workflows`_
@@ -142,7 +150,9 @@ Starting from version `24.0`_, all pull requests, development commits, and relea
 There are three `workflows`_: one for pull requests (`PR`_), one for the ``develop`` branch (`Develop`_), and one for the ``main`` branch (`Release`_).
 
   **Note**: Each workflow has a dedicated status badge in the `Ocelot README`_:
-  the `Release`_ |ReleaseButton| button and the `Develop`_ |DevelopButton| button, with the `PR`_ status being published directly in a pull request under the "Checks" tab.
+  the |ReleaseButton|:pdf:`\href{https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml}{Release}` button and
+  the |DevelopButton|:pdf:`\href{https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml}{Develop}` button,
+  with the `PR`_ status being published directly in a pull request under the "Checks" tab.
 
 The `PR`_ workflow will track code coverage using `Coveralls`_.
 After opening a pull request or submitting a new commit to a pull request, `Coveralls`_ will publish a short message with the current code coverage once the top commit is built.
@@ -164,11 +174,13 @@ Documentation
 .. _README: https://github.com/ThreeMammals/Ocelot/blob/main/docs/readme.md
 .. _Ocelot README: https://github.com/ThreeMammals/Ocelot/blob/main/README.md
 .. |ReleaseDocs| image:: https://readthedocs.org/projects/ocelot/badge/?version=latest&style=flat-square
-   :target: https://app.readthedocs.org/projects/ocelot/builds/?version__slug=latest
-   :alt: ReadTheDocs Status
+  :target: https://app.readthedocs.org/projects/ocelot/builds/?version__slug=latest
+  :alt: ReadTheDocs Status
+  :class: img-valign-middle
 .. |DevelopDocs| image:: https://readthedocs.org/projects/ocelot/badge/?version=develop&style=flat-square
-   :target: https://app.readthedocs.org/projects/ocelot/builds/?version__slug=develop
-   :alt: ReadTheDocs Status
+  :target: https://app.readthedocs.org/projects/ocelot/builds/?version__slug=develop
+  :alt: ReadTheDocs Status
+  :class: img-valign-middle
 .. _break3: http://break.do
 
   | Folder: ./`docs`_