feat: Docs

IngeniumSE · May 10, 2024 · f152f66 · f152f66
1 parent 0c500f0
commit f152f66
Show file tree

Hide file tree

Showing 32 changed files with 16,052 additions and 0 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
diff --git a/docs/babel.config.js b/docs/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/docs/blog/2019-05-28-first-blog-post.md b/docs/blog/2019-05-28-first-blog-post.md
@@ -0,0 +1,12 @@
+---
+slug: first-blog-post
+title: First Blog Post
+authors:
+  name: Gao Wei
+  title: Docusaurus Core Team
+  url: https://github.com/wgao19
+  image_url: https://github.com/wgao19.png
+tags: [hola, docusaurus]
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
diff --git a/docs/blog/2019-05-29-long-blog-post.md b/docs/blog/2019-05-29-long-blog-post.md
@@ -0,0 +1,44 @@
+---
+slug: long-blog-post
+title: Long Blog Post
+authors: endi
+tags: [hello, docusaurus]
+---
+
+This is the summary of a very long blog post,
+
+Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
+
+<!--truncate-->
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
diff --git a/docs/blog/2021-08-01-mdx-blog-post.mdx b/docs/blog/2021-08-01-mdx-blog-post.mdx
@@ -0,0 +1,20 @@
+---
+slug: mdx-blog-post
+title: MDX Blog Post
+authors: [slorber]
+tags: [docusaurus]
+---
+
+Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/).
+
+:::tip
+
+Use the power of React to create interactive blog posts.
+
+```js
+<button onClick={() => alert('button clicked!')}>Click me!</button>
+```
+
+<button onClick={() => alert('button clicked!')}>Click me!</button>
+
+:::
diff --git a/docs/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg b/docs/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg
diff --git a/docs/blog/2021-08-26-welcome/index.md b/docs/blog/2021-08-26-welcome/index.md
@@ -0,0 +1,25 @@
+---
+slug: welcome
+title: Welcome
+authors: [slorber, yangshun]
+tags: [facebook, hello, docusaurus]
+---
+
+[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
+
+Simply add Markdown files (or folders) to the `blog` directory.
+
+Regular blog authors can be added to `authors.yml`.
+
+The blog post date can be extracted from filenames, such as:
+
+- `2019-05-30-welcome.md`
+- `2019-05-30-welcome/index.md`
+
+A blog post folder can be convenient to co-locate blog post images:
+
+![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg)
+
+The blog supports tags as well!
+
+**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config.
diff --git a/docs/blog/authors.yml b/docs/blog/authors.yml
@@ -0,0 +1,17 @@
+endi:
+  name: Endilie Yacop Sucipto
+  title: Maintainer of Docusaurus
+  url: https://github.com/endiliey
+  image_url: https://github.com/endiliey.png
+
+yangshun:
+  name: Yangshun Tay
+  title: Front End Engineer @ Facebook
+  url: https://github.com/yangshun
+  image_url: https://github.com/yangshun.png
+
+slorber:
+  name: Sébastien Lorber
+  title: Docusaurus maintainer
+  url: https://sebastienlorber.com
+  image_url: https://github.com/slorber.png
diff --git a/docs/docs/client-usage.md b/docs/docs/client-usage.md
@@ -0,0 +1,107 @@
+---
+sidebar_position: 3
+tags: [HTTP Client, API Client, Dependency Injection]
+---
+
+# API Client Usage
+
+There are a number of ways to create an API client for accessing the WebTrends API. The approach you take will depend on how your app works.
+
+:::tip[Examples]
+
+Examples on this page are using the C# default constructors feature for brevity. The approaches listed here will work with typical constructors.
+
+:::
+
+## Using Dependency Injection (DI)
+
+You can use DI to inject a client into your app code. 
+
+### Using the default client
+
+The default client is pre-configured to use the configured `WebTrendsSettings`. The client will be disposed when the owning scope is disposed.
+
+```csharp
+public class MyService(IWebTrendsApiClient client)
+{
+  public async Task DoSomething()
+  {
+    // Do something with client.
+  }
+}
+```
+
+### Using the API client factory
+
+It is possible to inject the API client factory and settings instead. You need to manage the lifetime of the client itself.
+
+```csharp
+public class MyService(IWebTrendsApiClientFactory clientFactory, WebTrendsSettings settings)
+{
+  public async Task DoSomething()
+  {
+    using var client = clientFactory.CreateApiClient(settings);
+
+    // Do something with client.
+  }
+}
+```
+
+If you are not using the pre-configured `WebTrendsSettings`, you can provided your own:
+
+```csharp
+public class MyService(IWebTrendsApiClientFactory clientFactory)
+{
+  public async Task DoSomething()
+  {
+    var settings = new WebTrendsSettings();
+    using var client = clientFactory.CreateApiClient(settings);
+
+    // Do something with client.
+  }
+}
+```
+
+### Manually creating a client
+
+You can manually create a client yourself, but you are responsible for managing its lifetime. The following are some examples.
+
+#### Creating an API client manually
+
+```csharp
+var httpClient = new HttpClient();
+var settings = new WebTrendsSettings();
+
+var apiClient = new WebTrendsApiClient(httpClient, settings);
+```
+
+#### Creating an API client factory manually
+
+```csharp
+var httpClientFactory = new WebTrendsHttpClientFactory();
+var apiClientFactory = new WebTrendsApiClientFactory(httpClientFactory);
+var settings = new WebTrendsSettings();
+
+var apiClient = apiClientFactory.CreateApiClient(settings);
+```
+
+### Managing the HTTP Client
+
+If you need to control how the `HttpClient` is created, you can implement your own implementaton of `IWebTrendsHttpClientFactory`:
+
+```csharp
+public class MyWebTrendsHttpClientFactory : IWebTrendsHttpClientFactory
+{
+  public HttpClient CreateClient(string name)
+  {
+    return new HttpClient();
+  }
+}
+```
+
+If you are using the standard approach to dependency injection, you can register your own implementation, which will be used instead of the default implementation:
+
+```csharp
+services.AddWebTrends();
+services.AddScoped<IWebTrendsHttpClientFactory, MyWebTrendsHttpClientFactory>();
+```
diff --git a/docs/docs/configure.md b/docs/docs/configure.md
@@ -0,0 +1,95 @@
+---
+sidebar_position: 2
+title: Configure
+description: Details how to configure the WebTrendsSDK library within your project
+tags: [Getting started, Configuration]
+---
+
+# Configure
+
+The WebTrendsSDK targets .NET Standard 2.0 (`netstandard2.0`) which means you can install the SDK on any project that supports .NET Standard 2.0. You can view the [supported frameworks and platforms](https://www.nuget.org/packages/WebTrendsSDK#supportedframeworks-body-tab) on NuGet.org.
+
+## .NET Core and .NET 5+
+
+Apps written for the newer .NET platform can be configured to use the WebTrendsSDK through app configuration and service registration. 
+
+### Configuring WebTrends settings
+To configure the WebTrendsSDK, add the following to your `appsettings.json` file:
+
+```json
+{
+  "WebTrends": {
+    "AccountId": "{account_id}",
+    "KeyToken": "{token}",
+    "WebsiteUrl": "{website_url}
+  }
+}
+```
+
+The app configuration is mapped to the `WebTrendsSettings` type, which supports the following properties:
+
+| Property | Type | Default Value | Notes |
+| --- | --- | --- | --- |
+| `AccountId` | `string` | `null` | Your account ID |
+| `KeyToken` | `string` | `null` | Your authentication token |
+| `OtsBaseUrl` | `string` | https://ots.webtrends-optimize.com | The base URL for the WebTrends OTS REST API |
+| `CaptureRequestContent` | `bool` | `false` | If enabled, each request will capture the request content |
+| `CaptureResponseContent` | `bool` | `false` | If enabled, each request will capture the response content |
+
+### Service registration
+To add WebTrendsSDK services to your Dependency Injection container, you need to add a call to `AddWebTrends()` to your `IServiceCollection`. There are a few _flavours_ of a .NET app, so you'll need to decide which one you are using
+
+#### Using `WebApplication.CreateBuilder()`
+This is the typical approach to modern ASP.NET Core apps, typically using Minimal APIs.
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddWebTrends();
+```
+
+#### Using a Startup class
+This is an approach used by ASP.NET Core web apps.
+
+```csharp
+public class Startup
+{
+  public void ConfigureServices(IServiceCollection services)
+  {
+    services.AddWebTrends();
+  }
+}
+```
+
+#### Using `HostBuilder`
+The `HostBuilder` approach targets non-ASP.NET Core scenarios, such as Windows services, or Function apps (Azure Functions, AWS Lambda, etc.) that require host lifetime management.
+
+```csharp
+var builder = new HostBuilder()
+  .ConfigureServices(services => {
+    servies.AddWebTrends();
+  });
+```
+
+:::warning[Note on Lifetime]
+
+The `AddWebTrends()` extension method registers a per-scope lifetime for the default API client. This is typical for ASP.NET Core apps where the lifetime scope is per-request. For non-ASP.NET Core hosts, you may need to manage the lifetime through a lifetime scope, otherwise you may up with a singleton instance of the client.
+
+:::
+
+## .NET Framework
+
+### Vanilla .NET Framework
+
+If you are targeting .NET Framework but will be managing the lifetime of the SDK services yourself, you can easily create an instance of a client and settings. See [Client Usage](/docs/client-usage) for more information.
+
+### Integration through an Inversion of Control (IoC) container
+
+If you are targeting .NET Framework, you may or may not be using a IoC container, such as Autofac, or StructureMap, etc. It is possible to wire up the WebTrendsSDK using the same strategy as the default for ASP.NET Core, however as there are numerous IOC containers available, we haven't documented them here. Below is an outline of the recommended service lifetime for the services provided by the SDK:
+
+| Service | Implementation | Recommended Lifetime | Notes |
+| --- | --- | --- | --- |
+| `WebTrendsSettings` | `WebTrendsSettings` | `Singleton` | Pre-configure this instance. |
+| `IWebTrendsHttpClientFactory` | `WebTrendsHttpClientFactory` | `Scoped` | This is for customising a `HttpClient` instance. |
+| `IIsuuApiClientFactory` | `WebTrendsApiClientFactory` | `Scoped` | |
+| `IIsuuApiClient` | `WebTrendsApiClient` | `Scoped` | This is the default instance when injected directly. |