Merge pull request #466 from Green-Software-Foundation/docs/docusaurus

New documentation site with Docusaurus.  Reviewed all updated content and last round review requests.  Ready to Merge!  Thanks everyone and thanks @danuw for your tireless efforts on this one 👍

.github/workflows/6-jekyll-gh-pages.yml

@@ -0,0 +1,63 @@
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: 6-Deploy docs to GitHub Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["dev", "docs/*"]
+    paths:
+      - 'casdk-docs/**'
+      - 'samples/**'
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+   deploy:
+    name: Deploy docs to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Copy Files
+        run: |
+          # Moving the samples folder at build& deploy time of the docs so that it appears in the end result
+          cp -r ./samples/ ./casdk-docs/docs/
+        working-directory: .
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+        working-directory: ./casdk-docs
+      - name: Build website
+        run: yarn build
+        working-directory: ./casdk-docs
+
+      # Popular action to deploy to GitHub Pages:
+      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./casdk-docs/build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/verify-azure-function-with-packages.yaml

@@ -9,6 +9,7 @@ on:
       - 'src/**'
       - '.github/workflows/**'
       - 'samples/azure/azure-function/**'
+      - '!casdk-docs/**'
 
 env:
   DOCKERFILE_PATH: samples/azure/azure-function/Dockerfile

.gitignore

@@ -33,3 +33,5 @@ src/data/location-sources/custom-azure-zones.json
 
 # exclude artifacts on java-client example
 samples/java-client/target
+
+casdk-docs/docs/samples/*

README.md

@@ -99,7 +99,7 @@ deployment in the greenest location.
 
 The Carbon Aware SDK is being used by large and small companies around the
 world. Some of the world’s biggest enterprises and software companies, through
-to start-ups.  Both UBS and Vestas have used the SDK, with further details over on the [adopters overview](./docs/adopters.md).
+to start-ups.  Both UBS and Vestas have used the SDK, with further details over on the [adopters overview](./casdk-docs/docs/overview/adopters.md).
 
 Machine Learning (ML) workloads are a great example of long running compute
 intensive workloads, that often are also not time critical. By moving these workloads to a different time, the carbon emissions from the ML training can be reduced by up to 15%, and by moving the location of the training this can be
@@ -196,7 +196,6 @@ Open Source Working Group.
 
 ### Appointments
 The following are those who are currently actively working on the SDK and have made significant ongoing contributions.
-The following are those who are currently actively working on the SDK and have made significant ongoing contributions.
 
 - Chair/Project lead - Vaughan Knight (Microsoft)
 - Senior Technical Program Manager - Sophie Trinder (Green Software Foundation)

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,25 @@
+---
+slug: welcome
+title: Welcome to the Carbon Aware SDK documentation site
+tags: [welcome,post]
+---
+
+Carbon aware software does more when it can leverage greener energy sources, and less when the energy CO2 emissions are higher.  
+
+The Carbon Aware SDK is a toolset to help you measure the carbon emissions of your software, in turn helping you **measure and reduce your software's carbon emissions**, and choose when and where you run your software to make it greener.
+
+![Carbon Aware Software](./carbon-aware-software.png)
+
+
+By knowing the carbon emissions of the energy that powers your applications, you and your organisation can leverage greener energy sources to reduce your CO2 emissions by:  
+
+* Building  AI models when carbon emissions are lower
+* Deploying software into the cloud in locations that have greener energy sources
+* Running software updates at greener energy time windows 
+* Using data to run hypothetical models to understand how you could start driving impact and reduce emissions, drive business cases for change, and create a greener future. 
+
+Within the [Green Software Foundations Theory of Change](https://greensoftware.foundation/articles/theory-of-change), we look at 3 pillars, that being **Knowledge**, **Tech Culture**, and **Tooling** as focus areas to drive this change.  The Carbon Aware SDK at its core sits firmly in the **Tooling** pillar, and also supports the other pillars, providing **Knowledge** through emissions data to inform change, and being core enabler for the **Tech Culture** for building carbon aware software.
+
+Companies including UBS and Vestas have already deployed the Carbon Aware SDK to build greener software, and you can too!
+
+_Published in feb 2024 based on latest updates to the readme.md_

casdk-docs/blog/2022-10-01-release-1.0.mdx

@@ -0,0 +1,84 @@
+---
+slug: release-v1.0
+title: Release v1.0
+tags: [v1.0, release]
+---
+
+### Added 
+
+- Added Electricity Maps (paid api) support for forecasting and historical data.  
+- Added ElectricityMaps (free api) support for historical data.  Note that this API does not support forecast capabilities. 
+
+### Fixed
+
+- Fixed generated test data that had time bomb bug that was in test data, which caused integration tests to fail.  This is now automatically generated each time.
+- Fixed some bugs that related to underlying data source errors surfacing as HTTP 500 errors from the API.  These should now be more consistent.
+- Fixed an issue where UTF-8 passwords were encoded as ASCII for WattTime API, causing integration failure. 
+- Fixes some bugs in unit tests with uncaught scenarios, or faulty tests.
+
+### Changed
+
+- No previous API's were changed.  
+- Configuration has changed.  Refer to upgrading from 1.0.0 to 1.1.0 below.
+- Time is now always in UTC.  Previously the API may have returned local time depending on underlying API.
+
+#### API
+
+- `/locations` - Show the list of configured named locations that can be used in the API.
+- `/api/v1/swagger.yaml` - Provides OpenAPI document now at public endpoint when deployed.
+
+#### API Deployment
+
+- Configuration has changed.  Refer to upgrading from 1.0.0 to 1.1.0 below.
+
+#### SDK 
+
+- SDK was abstracted to provide a library for DLL import usage, which now allows users to use the SDK in their projects directly without the need to deploy an API.  This is useful in scenarios where the API can not be centralised.  Note - we still highly recommend centralising for management of the API and audit capabilities with observability.
+- Functionality for forecast and historical data have been seperated into seperate interfaces.  This impacts configuration, see upgrading from 1.0.0 to 1.1.0 for more information.
+- Additional tests across the SDK have been added.
+- Aggregation tier in the SDK was removed, this should not impact users of the SDK, but may impact maintainers who were actively contributing.
+
+
+#### Other
+
+- All contributors need to signoff commits for contribution using `git commit -s`.
+- Added PR release workflow improvements for the project management of the CA SDK project team.
+- Updated the project to prune stale PR's and issues to help with the management of the CA SDK project.
+
+
+### Upgrading from 1.0.0 to 1.1.0 
+
+- Configuration changes are required due to historical and forecast configuration now being decoupled.  Refer to - [Configuration](../docs/tutorial-extras/configuration) for a guide. The following is provided as an example of the new data source configuration format.
+```json
+{
+  "DataSources": {
+    "EmissionsDataSource": "Json",
+    "ForecastDataSource": "WattTime",
+    "Configurations": {
+      "WattTime": {
+        "Type": "WattTime",
+        "Username": "username",
+        "Password": "password",
+        "BaseURL": "https://api2.watttime.org/v2/",
+        "Proxy": {
+          "useProxy": true,
+          "url": "http://10.10.10.1",
+          "username": "proxyUsername",
+          "password": "proxyPassword"
+        }
+      },
+      "ElectricityMaps": {
+        "Type": "ElectricityMaps",
+        "APITokenHeader": "auth-token",
+        "APIToken": "myAwesomeToken",
+        "BaseURL": "https://api.electricitymap.org/v3/"
+      },
+      "Json": {
+        "Type": "Json",
+        "DataFileLocation": "test-data-azure-emissions.json"
+      }
+    }
+  }
+}
+```
+

casdk-docs/blog/2023-07-18-release-1.1.mdx

@@ -0,0 +1,84 @@
+---
+slug: release-v1.1
+title: Release v1.1
+tags: [v1.1, release]
+---
+
+### Added 
+
+- Added Electricity Maps (paid api) support for forecasting and historical data.  
+- Added ElectricityMaps (free api) support for historical data.  Note that this API does not support forecast capabilities. 
+
+### Fixed
+
+- Fixed generated test data that had time bomb bug that was in test data, which caused integration tests to fail.  This is now automatically generated each time.
+- Fixed some bugs that related to underlying data source errors surfacing as HTTP 500 errors from the API.  These should now be more consistent.
+- Fixed an issue where UTF-8 passwords were encoded as ASCII for WattTime API, causing integration failure. 
+- Fixes some bugs in unit tests with uncaught scenarios, or faulty tests.
+
+### Changed
+
+- No previous API's were changed.  
+- Configuration has changed.  Refer to upgrading from 1.0.0 to 1.1.0 below.
+- Time is now always in UTC.  Previously the API may have returned local time depending on underlying API.
+
+#### API
+
+- `/locations` - Show the list of configured named locations that can be used in the API.
+- `/api/v1/swagger.yaml` - Provides OpenAPI document now at public endpoint when deployed.
+
+#### API Deployment
+
+- Configuration has changed.  Refer to upgrading from 1.0.0 to 1.1.0 below.
+
+#### SDK 
+
+- SDK was abstracted to provide a library for DLL import usage, which now allows users to use the SDK in their projects directly without the need to deploy an API.  This is useful in scenarios where the API can not be centralised.  Note - we still highly recommend centralising for management of the API and audit capabilities with observability.
+- Functionality for forecast and historical data have been seperated into seperate interfaces.  This impacts configuration, see upgrading from 1.0.0 to 1.1.0 for more information.
+- Additional tests across the SDK have been added.
+- Aggregation tier in the SDK was removed, this should not impact users of the SDK, but may impact maintainers who were actively contributing.
+
+
+#### Other
+
+- All contributors need to signoff commits for contribution using `git commit -s`.
+- Added PR release workflow improvements for the project management of the CA SDK project team.
+- Updated the project to prune stale PR's and issues to help with the management of the CA SDK project.
+
+
+### Upgrading from 1.0.0 to 1.1.0 
+
+- Configuration changes are required due to historical and forecast configuration now being decoupled.  Refer to - [Configuration](../docs/tutorial-extras/configuration) for a guide. The following is provided as an example of the new data source configuration format.
+```json
+{
+  "DataSources": {
+    "EmissionsDataSource": "Json",
+    "ForecastDataSource": "WattTime",
+    "Configurations": {
+      "WattTime": {
+        "Type": "WattTime",
+        "Username": "username",
+        "Password": "password",
+        "BaseURL": "https://api2.watttime.org/v2/",
+        "Proxy": {
+          "useProxy": true,
+          "url": "http://10.10.10.1",
+          "username": "proxyUsername",
+          "password": "proxyPassword"
+        }
+      },
+      "ElectricityMaps": {
+        "Type": "ElectricityMaps",
+        "APITokenHeader": "auth-token",
+        "APIToken": "myAwesomeToken",
+        "BaseURL": "https://api.electricitymap.org/v3/"
+      },
+      "Json": {
+        "Type": "Json",
+        "DataFileLocation": "test-data-azure-emissions.json"
+      }
+    }
+  }
+}
+```
+