doc initial set up using classic template and typescript - doc is cur…

…rently copied into casdk-docs/docs to get live updates (copied and not moved so changes in main can be easily identified when rebasing once it all works)

casdk-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*

casdk-docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](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.

casdk-docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

casdk-docs/blog/2021-08-26-welcome/index.md

@@ -0,0 +1,15 @@
+---
+slug: welcome
+title: Welcome
+tags: [facebook, hello, docusaurus]
+---
+
+Welcome to our documentation site!
+
+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.

casdk-docs/blog/2023-08-01-mdx-blog-post.mdx

@@ -0,0 +1,19 @@
+---
+slug: release-v1.1
+title: Release v1.1
+tags: [v1.1, release]
+---
+
+Release 1.1
+
+:::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>
+
+:::

casdk-docs/docs/architecture/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Architecture",
+  "position": 3,
+  "link": {
+    "type": "generated-index"
+  }
+}

casdk-docs/docs/architecture/c-sharp-client-library.md

@@ -0,0 +1,211 @@
+# C\# Client Library
+
+This document outlines the designs behind the GSF Carbon Aware C# Client
+Library.
+
+## Namespace
+
+Given the fact this is going to be a library exposing functionality to
+consumers, will use the
+[standard](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/names-of-namespaces)
+namespace naming schema:
+`<Company>.(<Product>|<Technology>)[.<Feature>][.<Subnamespace>]`. For GSF
+CarbonAware SDK this the following schema:
+
+- **Company**: **_GSF_**
+- **Product**: **_CarbonAware_**
+- **Feature**: **_Models_**, **_Handlers_**, ...
+
+An example of a namespace would be: `namespace GSF.CarbonAware.Models` and a
+class (record, interface, ...) that belongs to that namespace would be:
+
+```c#
+namespace GSF.CarbonAware.Models;
+
+public record EmissionsData
+{
+    ....
+}
+```
+
+The following namespaces are included:
+
+| namespace                     |
+| ----------------------------- |
+| GSF.CarbonAware.Exceptions    |
+| GSF.CarbonAware.Configuration |
+| GSF.CarbonAware.Handlers      |
+| GSF.CarbonAware.Models        |
+| GSF.CarbonAware.Parameters    |
+
+## Features
+
+### Models
+
+There are two main classes that represents the data fetched from the data
+sources (i.e `Static Json`, [WattTime](https://www.watttime.org),
+[ElectricityMaps](https://www.electricitymaps.com), and
+[ElectricityMapsFree](https://www.co2signal.com/)):
+
+- `EmissionsData`
+- `EmissionsForecast`
+
+A record is defined for each of these data types owned by the library.
+
+```c#
+namespace GSF.CarbonAware.Models;
+public record EmissionsData
+{
+    string Location
+    DateTimeOffset Time
+    double Rating
+    TimeSpan Duration
+}
+```
+
+```c#
+namespace GSF.CarbonAware.Models;
+public record EmissionsForecast
+{
+    DateTimeOffset RequestedAt
+    DateTimeOffset GeneratedAt
+    IEnumerable<EmissionsData> EmissionsDataPoints
+    IEnumerable<EmissionsData> OptimalDataPoints
+}
+```
+
+The user can expect to either have a primitive type (such as an int) or one of
+these specific models as a return type of the **Handlers**.
+
+### Handlers
+
+There will be two handlers for each of the data types returned:
+
+- `EmissionsHandler`
+- `ForecastHandler`
+
+Each is responsible for interacting on its own domain. For instance,
+EmissionsHandler can have a method `GetAverageCarbonIntensityAsync()` to pull
+EmissionsData data from a configured data source and calculate the average
+carbon intensity. ForecastHandler can have a method `GetCurrentAsync()`, that
+will return a EmissionsForecast instance. (**Note**: The current core
+implementation is using async/await paradigm, which would be the default for
+library too).
+
+In addition, there is a `LocationHandler` that is responsible for retrieving all
+the locations supported by the underlying datasource.
+
+### Parameters
+
+Both handlers require that exact fields be passed in as input. Within the docs
+of each library function, we specifically call out which fields the function
+expects to be defined versus which are optional. Internally, we handle creating
+the CarbonAwareParameters object and validating the fields through that.
+
+## Carbon Aware Parameters
+
+The `CarbonAwareParameters` class allows the user to pass in a unique parameter
+instance to the public methods in the Handlers with the specific parameters
+needed by that call. The list of allowed parameters is defined in the class and
+includes
+
+- SingleLocation
+- MultipleLocations
+- Start
+- End
+- RequestedAt
+- Duration
+
+### Parameter Display Names
+
+The display name of each parameter can be overriden using the public setter. By
+default, each parameter display name is set to the variable name (ex:
+`Start = "start"`). The parameter display names are used when creating the
+validation error messages. Overriding them is useful in situations where the
+variables the user is using for input don't exactly match the default display
+name of the parameter (e.g. the user variable in the controller is
+`periodStartTime` instead of `startTime`). That way, when the error is thrown to
+the user, the parameter names will match the users' expectation
+
+To do the override, define a class that inherits from
+CarbonAwareParametersBaseDTO and uses the [FromQuery(Name =
+"myAwesomeDisplayName")] or [JsonPropertyName("myAwesomeDisplayName")]
+attribute. A second (less recommended) option is to pass the optional arg
+Dictionary<string, string>? displayNameMap when you are directly creating the
+object. With either option, the SDK handles updating references internally.
+
+### Required Properties
+
+The first core check the parameters class does is validating that required
+parameters are defined. By default, all parameters are considered optional.
+Calling the `SetRequiredProperties(...)` function with the desired arguments
+sets the required parameters for the instance.
+
+```csharp
+    /// <summary>
+    /// Accepts any PropertyNames as arguments and sets the associated property as required for validation.
+    /// </summary>
+    public void SetRequiredProperties(params PropertyName[] requiredProperties)
+```
+
+### Validations
+
+The second core check the parameters class does is enforcing validations on the
+parameters themselves. Some common examples include
+
+- Relationship validations: _`start < end` must be true_
+- Content validations: _`list.Any()` must be true for list fields_
+
+Calling the `SetValidations(...)` function with the desired arguments sets the
+validations for the instance.
+
+```csharp
+    /// <summary>
+    /// Accepts any ValidationName as arguments and sets the associated validation to check.
+    /// </summary>
+    public void SetValidations(params ValidationName[] validationNames)
+```
+
+### Validate
+
+Calling the `Validate(...)` function validates (1) required parameters and (2)
+specified validations. Currently, the only validation we check is whether
+`start` is before `end`.
+
+If no errors are thrown, the function simply returns. If any validation errors
+are found, they are packaged into a single `ArgumentException` error with each
+being part of the `data` dictionary.
+
+```
+    /// <summary>
+    /// Validates the properties and relationships between properties. Any validation errors found are packaged into an
+    /// ArgumentException and thrown. If there are no errors, simply returns void.
+    /// </summary>
+    public void Validate()
+```
+
+### Getters With Default Fallbacks
+
+Certain parameters have special getters that allow you to define a fallback
+default value if the parameter is null. This can be useful in cases where a
+parameter is optional, so you want to get it if it was defined by the user, or
+otherwise fallback to a specific default. These include `Start`, `End`,
+`Requested`,and `Duration`
+
+```
+   DateTimeOffset StartOrDefault(DateTimeOffset defaultStart)
+   DateTimeOffset EndOrDefault(DateTimeOffset defaultEnd)
+   DateTimeOffset RequestedOrDefault(DateTimeOffset defaultRequested)
+   TimeSpan DurationOrDefault
+
+```
+
+### Error Handling
+
+The `CarbonAwareException` class is used to report errors to the consumer. It
+follows the `Exception` class approach, where messages and details are provided
+as part of error reporting.
+
+## References
+
+<https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/>