Arrange versioned docs

restsharp · Jun 25, 2024 · c6c8b2f · c6c8b2f
1 parent ab2e3a7
commit c6c8b2f
Show file tree

Hide file tree

Showing 12 changed files with 825 additions and 781 deletions.
diff --git a/docs/docs/changelog.md b/docs/docs/changelog.md
@@ -1,37 +1,11 @@
 ---
 title: What's new
-description: List of changes per RestSharp version.
+description: List of changes for the current major version
 sidebar_position: 2
 ---
 
 # Changelog
 
-This changelog is only maintained since v111. For release notes of previous versions, please check the [Releases page](https://github.com/restsharp/RestSharp/releases) in RestSharp GitHub repository.
+For release notes of previous versions, please check the [Releases page](https://github.com/restsharp/RestSharp/releases) in RestSharp GitHub repository.
 
-Only the most important or breaking changes are listed there. All other changes can be found in each release on GitHub.
-
-## v111.3
-
-New extensions:
-* `RestResponse.GetHeader` for getting one response header value
-* `RestResponse.GetHeaders` for getting a collection of header values
-* `IRestClient.(Execute)Get(Async)` with string resource instead of request object
-* `IRestClient.(Execute)Delete(Async)` with string resource instead of request object
-
-## v111.2
-
-* `Execute` extensions that were accidentally removed from v111 are back
-* Several authenticators got renamed by unintentional refactoring, that change has also been reverted.
-
-## v111.0
-
-> The package for v111.0 is listed as unsupported on NuGet as it has API changes that weren't planned. Use the patched version v111.2 or later.
-
-* Added [interceptors](advanced/interceptors.md).
-* As interceptors provide a better way to interject the request and response execution flow, request properties `OnBeforeRequest`, `OnBeforeDeserialization` and `OnAfterRequest` are marked obsolete and will be removed in future versions.
-* **Breaking change.** Client option `MaxTimeout` renamed to `Timeout` and changed type to `Timespan` for clarity. It doesn't configure the `HttpClient` timeout anymore. Instead, the same method is used for client and request level timeouts with cancellation tokens.
-* **Breaking change.** Request option `Timeout` changed type to `Timespan` for clarity.
-* Added .NET 8 target.
-* Support uploading files as content without multipart form.
-* Added `CacheControl` options to client and requests.
-* Allow using `AddJsonBody` to serialize top-level strings.
+Changes between major versions are documented in the documentation for each version on this website.
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -3,108 +3,119 @@ import type * as Preset from "@docusaurus/preset-classic";
 import {themes} from "prism-react-renderer";
 
 const config: Config = {
-  title: "RestSharp",
-  tagline: "Simple REST and HTTP API Client for .NET",
-  favicon: "img/favicon.ico",
-  url: "https://restsharp.dev",
-  baseUrl: "/",
-  onBrokenLinks: "throw",
-  onBrokenMarkdownLinks: "warn",
-  i18n: {
-    defaultLocale: "en",
-    locales: ["en"],
-  },
-
-  presets: [
-    [
-      "classic",
-      {
-        docs: {
-          sidebarPath: "./sidebars.ts",
-        },
-        theme: {
-          customCss: "./src/css/custom.css",
-        },
-      } satisfies Preset.Options,
-    ],
-  ],
-
-  themeConfig: {
-    navbar: {
-      title: "RestSharp",
-      logo: {
-        alt: "RestSharp Logo",
-        src: "img/restsharp.png",
-      },
-      items: [
-        {
-          type: "docSidebar",
-          sidebarId: "tutorialSidebar",
-          position: "left",
-          label: "Documentation",
-        },
-        {
-          href: "/migration",
-          label: "Migration"
-        },
-        {
-          href: "/support",
-          label: "Support",
-        },
-        {
-          href: 'https://github.com/RestSharp/RestSharp',
-          label: "GitHub",
-          position: "right",
-        },
-      ],
+    title: "RestSharp",
+    tagline: "Simple REST and HTTP API Client for .NET",
+    favicon: "img/favicon.ico",
+    url: "https://restsharp.dev",
+    baseUrl: "/",
+    onBrokenLinks: "throw",
+    onBrokenMarkdownLinks: "warn",
+    i18n: {
+        defaultLocale: "en",
+        locales: ["en"],
     },
-    footer: {
-      style: "dark",
-      links: [
-        {
-          title: "Docs",
-          items: [
-            {
-              label: "Documentation",
-              to: "/docs/intro",
-            },
-          ],
-        },
-        {
-          title: "Community",
-          items: [
-            {
-              label: "Stack Overflow",
-              href: "https://stackoverflow.com/questions/tagged/restsharp",
+
+    presets: [[
+        "classic", {
+            docs: {
+                editUrl: "https://github.com/RestSharp/RestSharp/tree/dev/docs",
+                sidebarPath: "./sidebars.ts",
+                includeCurrentVersion: true,
+                versions: {
+                    "v111": {
+                        label: "v111"
+                    },
+                    "v110": {
+                        label: "v110"
+                    }
+                }
             },
-            {
-              label: "Discord",
-              href: "https://discordapp.com/invite/docusaurus",
+            theme: {
+                customCss: "./src/css/custom.css",
             },
-            {
-              label: "Twitter",
-              href: "https://twitter.com/RestSharp",
+        } satisfies Preset.Options,
+    ]],
+
+    themeConfig: {
+        navbar: {
+            title: "RestSharp",
+            logo: {
+                alt: "RestSharp Logo",
+                src: "img/restsharp.png",
             },
-          ],
+            items: [
+                {
+                    type: "docSidebar",
+                    sidebarId: "tutorialSidebar",
+                    position: "left",
+                    label: "Documentation",
+                },
+                {
+                    href: "/migration",
+                    label: "Migration from v106"
+                },
+                {
+                    href: "/support",
+                    label: "Support",
+                },
+                {
+                    type: "docsVersionDropdown",
+                    position: "right",
+                },
+                {
+                    href: 'https://github.com/RestSharp/RestSharp',
+                    label: "GitHub",
+                    position: "right",
+                },
+            ],
         },
-        {
-          title: "More",
-          items: [
-            {
-              label: "GitHub",
-              href: "https://github.com/RestSharp/RestSharp",
-            },
-          ],
+        footer: {
+            style: "dark",
+            links: [
+                {
+                    title: "Docs",
+                    items: [
+                        {
+                            label: "Documentation",
+                            to: "/docs/intro",
+                        },
+                    ],
+                },
+                {
+                    title: "Community",
+                    items: [
+                        {
+                            label: "Stack Overflow",
+                            href: "https://stackoverflow.com/questions/tagged/restsharp",
+                        },
+                        {
+                            label: "Discord",
+                            href: "https://discordapp.com/invite/docusaurus",
+                        },
+                        {
+                            label: "Twitter",
+                            href: "https://twitter.com/RestSharp",
+                        },
+                    ],
+                },
+                {
+                    title: "More",
+                    items: [
+                        {
+                            label: "GitHub",
+                            href: "https://github.com/RestSharp/RestSharp",
+                        },
+                    ],
+                },
+            ],
+            copyright: `Copyright © ${new Date().getFullYear()} .NET Foundation. Built with Docusaurus.`,
         },
-      ],
-      copyright: `Copyright © ${new Date().getFullYear()} .NET Foundation. Built with Docusaurus.`,
-    },
-    prism: {
-      theme: themes.vsLight,
-      darkTheme: themes.vsDark,
-      additionalLanguages: ['csharp'],
-    },
-  } satisfies Preset.ThemeConfig,
+        prism: {
+            theme: themes.vsLight,
+            darkTheme: themes.vsDark,
+            additionalLanguages: ['csharp'],
+        },
+    } satisfies Preset.ThemeConfig,
 };
 
 export default config;
diff --git a/docs/versioned_docs/version-v110/changelog.md b/docs/versioned_docs/version-v110/changelog.md
@@ -1,37 +1,24 @@
 ---
 title: What's new
-description: List of changes per RestSharp version.
+description: List of changes for the current major version
 sidebar_position: 2
 ---
 
 # Changelog
 
-This changelog is only maintained since v111. For release notes of previous versions, please check the [Releases page](https://github.com/restsharp/RestSharp/releases) in RestSharp GitHub repository.
+For release notes of previous versions, please check the [Releases page](https://github.com/restsharp/RestSharp/releases) in RestSharp GitHub repository.
 
-Only the most important or breaking changes are listed there. All other changes can be found in each release on GitHub.
+## What's Changed
+* Added default parameters to the request. They got missing somehow.
+* Consider the boundary quotes request option value.
+* Made `BuildUrl` an extension so it can be used publicly.
+* Added client-level cookie container.
 
-## v111.3
+## Breaking change
 
-New extensions:
-* `RestResponse.GetHeader` for getting one response header value
-* `RestResponse.GetHeaders` for getting a collection of header values
-* `IRestClient.(Execute)Get(Async)` with string resource instead of request object
-* `IRestClient.(Execute)Delete(Async)` with string resource instead of request object
+The `IRestClient` interface signature is different, so any non-standard implementations need to adopt the changes.
 
-## v111.2
+To keep `DefaultParameters` thread-safe, it got a new type `DefaultParameters`, and request property `Parameters` has a dedicated type `RequestParameter`. Code-wise the change is non-breaking as the signatures are the same, but v110 is not binary compatible with previous versions. The difference is that `DefaultParameters` collection wraps all its mutations in a lock.
 
-* `Execute` extensions that were accidentally removed from v111 are back
-* Several authenticators got renamed by unintentional refactoring, that change has also been reverted.
+**Full Changelog**: https://github.com/restsharp/RestSharp/compare/109.0.1...110.0.0
 
-## v111.0
-
-> The package for v111.0 is listed as unsupported on NuGet as it has API changes that weren't planned. Use the patched version v111.2 or later.
-
-* Added [interceptors](advanced/interceptors.md).
-* As interceptors provide a better way to interject the request and response execution flow, request properties `OnBeforeRequest`, `OnBeforeDeserialization` and `OnAfterRequest` are marked obsolete and will be removed in future versions.
-* **Breaking change.** Client option `MaxTimeout` renamed to `Timeout` and changed type to `Timespan` for clarity. It doesn't configure the `HttpClient` timeout anymore. Instead, the same method is used for client and request level timeouts with cancellation tokens.
-* **Breaking change.** Request option `Timeout` changed type to `Timespan` for clarity.
-* Added .NET 8 target.
-* Support uploading files as content without multipart form.
-* Added `CacheControl` options to client and requests.
-* Allow using `AddJsonBody` to serialize top-level strings.
diff --git a/docs/versioned_docs/version-v111/advanced/configuration.md b/docs/versioned_docs/version-v111/advanced/configuration.md
@@ -28,7 +28,7 @@ Constructor parameters are:
 | options                 | Client options                                                                                                                                              | Yes       |
 | configureDefaultHeaders | Function to configure headers. Allows to configure default headers for `HttpClient`. Most of the time you'd prefer using `client.AddDefaultHeader` instead. | No        |
 | configureSerialization  | Function to configure client serializers with non-default options or to use a different serializer ([learn more](serialization.md))                         | No        |
-| useClientFactory        | Instructs the client to use `SimpleFactory` ([learn more](../usage/usage.md#simple-factory)) to get an `HttpClient` instance                                | No        |
+| useClientFactory        | Instructs the client to use `SimpleFactory` ([learn more](../usage/basics#simple-factory)) to get an `HttpClient` instance                                | No        |
 
 Here's an example of how to create a client using client options:
 
@@ -227,4 +227,4 @@ Client options apply to all requests made by the client. Sometimes, you want to
 | `AdvancedResponseWriter`     | Allows custom handling of the response. The function gets an instance of `HttpResponseMessage` and an instance of `RestRequest`. It must return an instance of `RestResponse`, so it effectively overrides RestSharp default functionality for creating responses.                                                |
 | `Interceptors`               | Allows adding interceptors to the request. Both client-level and request-level interceptors will be called.                                                                                                                                                                                                       |
 
-The table below contains all configuration properties of `RestRequest`. To learn more about adding request parameters, check the [usage page](../usage/usage.md#create-a-request) section about creating requests with parameters.
+The table below contains all configuration properties of `RestRequest`. To learn more about adding request parameters, check the [usage page](../usage/basics#create-a-request) section about creating requests with parameters.
diff --git a/docs/versioned_docs/version-v111/changelog.md b/docs/versioned_docs/version-v111/changelog.md
@@ -1,6 +1,6 @@
 ---
 title: What's new
-description: List of changes per RestSharp version.
+description: List of changes for the current major version
 sidebar_position: 2
 ---
 
@@ -15,23 +15,35 @@ Only the most important or breaking changes are listed there. All other changes
 New extensions:
 * `RestResponse.GetHeader` for getting one response header value
 * `RestResponse.GetHeaders` for getting a collection of header values
-* `IRestClient.(Execute)Get(Async)` with string resource instead of request object
-* `IRestClient.(Execute)Delete(Async)` with string resource instead of request object
+* `IRestClient.(Execute)Get(Async)` with string resource instead of a request object
+* `IRestClient.(Execute)Delete(Async)` with string resource instead of a request object
+
+[Full changelog](https://github.com/restsharp/RestSharp/releases/tag/111.3.0)
 
 ## v111.2
 
 * `Execute` extensions that were accidentally removed from v111 are back
 * Several authenticators got renamed by unintentional refactoring, that change has also been reverted.
 
+[Full changelog](https://github.com/restsharp/RestSharp/releases/tag/111.2.0)
+
 ## v111.0
 
-> The package for v111.0 is listed as unsupported on NuGet as it has API changes that weren't planned. Use the patched version v111.2 or later.
+:::warning
+Package for v111.0 and v111.1 are listed as unsupported on NuGet as there are API changes that weren't planned. 
+Use the patched version v111.2 or later.
+:::
 
+### Breaking changes
+* Client option `MaxTimeout` renamed to `Timeout` and changed type to `Timespan` for clarity. It doesn't configure the `HttpClient` timeout anymore. Instead, the same method is used for client and request level timeouts with cancellation tokens.
+* Request option `Timeout` changed type to `Timespan` for clarity.
+
+### New features
 * Added [interceptors](advanced/interceptors.md).
 * As interceptors provide a better way to interject the request and response execution flow, request properties `OnBeforeRequest`, `OnBeforeDeserialization` and `OnAfterRequest` are marked obsolete and will be removed in future versions.
-* **Breaking change.** Client option `MaxTimeout` renamed to `Timeout` and changed type to `Timespan` for clarity. It doesn't configure the `HttpClient` timeout anymore. Instead, the same method is used for client and request level timeouts with cancellation tokens.
-* **Breaking change.** Request option `Timeout` changed type to `Timespan` for clarity.
 * Added .NET 8 target.
-* Support uploading files as content without multipart form.
+* Support for uploading files as content without multipart form.
 * Added `CacheControl` options to client and requests.
 * Allow using `AddJsonBody` to serialize top-level strings.
+
+[Full changelog](https://github.com/restsharp/RestSharp/releases/tag/111.0.0)
diff --git a/docs/versioned_docs/version-v111/intro.md b/docs/versioned_docs/version-v111/intro.md
@@ -74,7 +74,7 @@ var client = new RestClient(options);
 var timeline = await client.GetJsonAsync<HomeTimeline>("statuses/home_timeline.json", cancellationToken);
 ```
 
-Read [here](usage/usage.md#json-requests) about making JSON calls without preparing a request object.
+Read [here](usage/basics#json-requests) about making JSON calls without preparing a request object.
 
 ### Content type