[OPS-500] Move docs to build with Docusaurus3

docs/.gitignore

@@ -0,0 +1,4 @@
+# Site-config
+!*./site-config/sidebars.json
+!*./site-config/release-notes.md
+site-config

docs/README.md

@@ -1,20 +1,69 @@
-
-# Building the documentation Site
+# Docs with Docusaurus 3
 
-This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
+## Requirements:
+- make
+- container utility (tested with `docker` and `podman`)
 
-### Installation
+> NOTE: on Windows, it's highly recommended to use WSL to build docs. Look for `Windows` notes below
 
-    npm ci
+## TLDR;
 
-### Local Development
+- To build, run `make build` in `docs` folder of your repository. The default build is using `docker`, if you want to use `podman`, run
+```bash
+export DOCKER=@podman
+```
+before running any make command.
 
-    npm start
+- To serve the project to see the site is fine, run `make serve` after building.
+- To live-serve while working, run `make start`.
+- To clean things and start over, run `make clean`.
 
-This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
 
-### Build
+# Details
+
+## Layout
+
+This is a docs layout that is utilised by Docusaurus (and our CI) to build static documentation. The layout is as follows:
+
+- docs (where the `next` version content lives)
+- archive (where the previous versions live)
+- site-config (where the sidebar and release-notes.md reside and where the actual build happens)
+- Makefile for convenient work flows
+- README
+
+As per usual, edit docs in the `docs` folder, and update the sidebar if you need to in `site-config` folder.
+
+## How it works
+
+The heart of the build is in the `pipeline-docusaurus` pipeline container. It includes all the templates needed to create a Docusaurus website, 
+and those templates, populated, are placed into the site-config directory for the build. These include `package.json`, `package-lock.json`, as well
+as docusarus configuration. Additionally, cached `node-modules` are linked for the build purposes.
+
+This makes out-of-container builds complicated, as such builds within the container are always recommended.
+
+### How to build
+
+To build the docs site, one need to run a script within a container that does all the work. It is highly recommended to just use make commands that
+run the container with all the required options. In general though, the following is performed:
+
+- The 'current' (docs folder of the repository) is mounted in the container as `/docs`
+- The templates are copied over from /templates into the `/docs/site-config` and populated appropriately
+- The `/node-modules` is linked inside `/docs/site-config`
+- The `/docs/docs` is mounted inside `/docs/site-config`
+- The local `.npmrc` is linked inside `/docs/site-config`
+- The build is run in the `/docs/site-config` directory
+
+### Windows notes
+
+If you work on your project on Windows file system, and you only need to work on the docs once in a while, it's recommended to setup WSL, 
+install `make` and `docker/podman`, and perform builds directly on the Windows mount point (i.e. something like `/mnt/c/...`). However, these
+builds will be somewhat slow, which might be okay for a now-and-then use cases. The reason is that the mount (`/mnt/c`) is actually network-simulated, and
+to build, npm will need to "fetch" all it needs via this network simulation. Additionally, using `npm start` for live-reload will not work, as this combination
+does not support `inotify` functionality, hence live reload will not see the changed files.
+
+If you need faster builds, and work a lot with the documentation, and work often with the live-reload feature (`npm start`), the alternative is to actually
+copy the project into the local WSL environment (for example, `/home/alex/...` on you WSL installation), and run all the builds in that environment. The documentation edits
+are still possible with any Windows tool via the reverse network mount (SMB, `\\wsl$\<Linux>\home\alex\...`), but the benefit of this is the speed of the builds, and the ability
+to `watch` filesystem changes, which are not possible in the first option.
 
-    npm run-script build
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.

docs/versioned_docs/version-0.21.0/datamodel.mdx → docs/archive/versioned_docs/version-0.21.0/datamodel.mdx

@@ -18,7 +18,7 @@ profile. CIM profiles are subsets of the whole CIM standard that dictates which
 publishes its model at [https://zepben.bitbucket.io/cim/evolve/](https://zepben.bitbucket.io/cim/evolve/).
 
 If the Evolve profile doesn't contain a part of CIM that you require for your use case, you can request or propose a change to the model
-by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at <https://www.zepben.com/contact>.
+by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at \<https://www.zepben.com/contact\>.
 
 ## Getting Started With The Model
 

docs/versioned_docs/version-0.25.0/datamodel.mdx → docs/archive/versioned_docs/version-0.22.0/datamodel.mdx

@@ -18,7 +18,7 @@ profile. CIM profiles are subsets of the whole CIM standard that dictates which
 publishes its model at [https://zepben.github.io/evolve/docs/cim/evolve/](https://zepben.github.io/evolve/docs/cim/evolve/).
 
 If the Evolve profile doesn't contain a part of CIM that you require for your use case, you can request or propose a change to the model
-by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at <https://www.zepben.com/contact>.
+by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at \<https://www.zepben.com/contact\>.
 
 ## Getting Started With The Model
 

docs/versioned_docs/version-0.22.0/datamodel.mdx → docs/archive/versioned_docs/version-0.23.0/datamodel.mdx

@@ -18,7 +18,7 @@ profile. CIM profiles are subsets of the whole CIM standard that dictates which
 publishes its model at [https://zepben.github.io/evolve/docs/cim/evolve/](https://zepben.github.io/evolve/docs/cim/evolve/).
 
 If the Evolve profile doesn't contain a part of CIM that you require for your use case, you can request or propose a change to the model
-by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at <https://www.zepben.com/contact>.
+by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at \<https://www.zepben.com/contact\>.
 
 ## Getting Started With The Model
 

docs/versioned_docs/version-0.23.0/datamodel.mdx → docs/archive/versioned_docs/version-0.24.0/datamodel.mdx

@@ -18,7 +18,7 @@ profile. CIM profiles are subsets of the whole CIM standard that dictates which
 publishes its model at [https://zepben.github.io/evolve/docs/cim/evolve/](https://zepben.github.io/evolve/docs/cim/evolve/).
 
 If the Evolve profile doesn't contain a part of CIM that you require for your use case, you can request or propose a change to the model
-by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at <https://www.zepben.com/contact>.
+by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at \<https://www.zepben.com/contact\>.
 
 ## Getting Started With The Model
 

docs/versioned_docs/version-0.24.0/datamodel.mdx → docs/archive/versioned_docs/version-0.25.0/datamodel.mdx

@@ -18,7 +18,7 @@ profile. CIM profiles are subsets of the whole CIM standard that dictates which
 publishes its model at [https://zepben.github.io/evolve/docs/cim/evolve/](https://zepben.github.io/evolve/docs/cim/evolve/).
 
 If the Evolve profile doesn't contain a part of CIM that you require for your use case, you can request or propose a change to the model
-by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at <https://www.zepben.com/contact>.
+by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at \<https://www.zepben.com/contact\>.
 
 ## Getting Started With The Model
 

docs/archive/versioned_docs/version-0.26.0/datamodel.mdx

@@ -0,0 +1,217 @@
+---
+id: sdk-data-model
+title: Data Model
+slug: /
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The Evolve SDK provides the building blocks you need to interface with the rest of the platform. It can also be used to
+build your own solutions from scratch that will be compatible with other things built with the SDK.
+
+## CIM Model
+
+The Evolve platform is composed around a domain model based on the 'Common Information Model' (CIM). The CIM is a very
+large standard that covers a huge amount of use cases. To make things more digestible, Evolve publishes its own CIM
+profile. CIM profiles are subsets of the whole CIM standard that dictates which parts of the model are in use. Evolve
+publishes its model at [https://zepben.github.io/evolve/docs/cim/evolve/](https://zepben.github.io/evolve/docs/cim/evolve/).
+
+If the Evolve profile doesn't contain a part of CIM that you require for your use case, you can request or propose a change to the model
+by starting a discussion at the [Evolve GitHub discussions](https://github.com/zepben/evolve/discussions) or by contacting Zepben directly at \<https://www.zepben.com/contact\>.
+
+## Getting Started With The Model
+
+:::tip
+All things that have an ID in the CIM model inherit from
+[IdentifiedObject](https://zepben.github.io/evolve/docs/cim/cim100/TC57CIM/IEC61970/Base/Core/IdentifiedObject). This provides common
+attributes such as mRID (master resource identifier), name, description, etc.
+:::
+
+Let's get started with the data model by building the following contrived electrical circuit.
+
+![](./assets/contrived-circuit.png)
+
+Here we simply have an AC energy source ([EnergySource](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Wires/EnergySource/))
+connected to a conductor ([ACLineSegment](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Wires/ACLineSegment/))
+connected to a circuit breaker ([Breaker](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Wires/Breaker/)).
+In CIM all these things are a subtype of 
+[ConductingEquipment](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/ConductingEquipment/).
+
+Let's see how we create them:
+
+```python
+from zepben.evolve import EnergySource, AcLineSegment, Breaker
+
+# Create the energy source. Providing no ID will generate a UUID.
+source = EnergySource()
+
+# Create the conductor providing a specific ID.
+acls = AcLineSegment("aclineseg1")
+
+# Create a circuit breaker.
+# A UUID will be generated but we can give it a descriptive name.
+breaker = Breaker(name="my circuit breaker")
+```
+
+## Creating Connectivity
+
+In CIM, all conducting equipment can have any number of [Terminals](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/Terminal/),
+and terminals connect to other terminals using a [ConnectivityNode](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/ConnectivityNode/).
+If we redraw the above diagram with all the required items from CIM it would look like:
+
+![](./assets/contrived-circuit-cim.png)
+
+Where the back dots represent the terminals and the black diamonds represent connectivity nodes.
+
+Now, lets redo the above code sample this time also creating connectivity between the objects.
+
+```python
+from zepben.evolve import EnergySource, AcLineSegment, Terminal, Breaker, ConnectivityNode
+
+# Create the energy source
+source = EnergySource()
+
+# Create the terminal for the energy source and associate it with the source
+source_t1 = Terminal(conducting_equipment=source)
+source.add_terminal(source_t1)
+
+# Create the conductor
+acls = AcLineSegment()
+
+# Create a terminal for each end of the conductor
+# and associate them with the conductor
+acls_t1 = Terminal(conducting_equipment=acls)
+acls_t2 = Terminal(conducting_equipment=acls)
+acls.add_terminal(acls_t1)
+acls.add_terminal(acls_t2)
+
+# Create a circuit breaker
+breaker = Breaker()
+
+# Create a terminal for the breaker
+breaker_t1 = Terminal(conducting_equipment=breaker)
+
+# Now create a connectivity node to connect the source terminal
+# to the conductor's first terminal
+cn1 = ConnectivityNode()
+
+# Now associate the connectivity nodes to the terminals
+cn1.add_terminal(source_t1)
+source_t1.connectivity_node = cn1
+cn1.add_terminal(acls_t1)
+acls_t1.connectivity_node = cn1
+
+# Now create a connectivity node to connect the source terminal
+# to the conductor's first terminal
+cn2 = ConnectivityNode()
+
+# Now associate the connectivity nodes to the terminals
+cn2.add_terminal(acls_t2)
+acls_t2.connectivity_node = cn2
+cn2.add_terminal(breaker_t1)
+breaker_t1.connectivity_node = cn2
+```
+
+## Normal and Current states
+
+As the network is a dynamic model (that is things like switches can be open and closed), many things in the model support 
+the notion of 'normal' and 'current'. For example, a switch has a normally open state and a currently open state. 
+This allows you to perform analysis on the model considering the normal or current state of the network, and allows you 
+to tell if the network is currently in the normal state or not. This can be important when making decisions based on 
+analytics you may be running when using the model.
+
+```python
+from zepben.evolve import Breaker
+
+# Example of setting normal and current switch states
+switch = Breaker()
+switch.set_normally_open(True)
+switch.set_open(False)
+```
+
+## Phases 
+
+Phases in CIM are set on a [Terminal](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/Terminal). The `phases`
+property on the terminal should be considered as the terminal's 'nominal' phases. The vast majority of the time, this will
+be the actual active phases at that terminal. However, due to the dynamic nature of the network, it's possible that when
+tracing connecitvity that the active phase at the terminal is different. The phase can be tracked using the `traced_phases`
+property on the terminal. 
+
+:::tip
+There are a number of helpful functions for tracing phases based on connectivity. See [tracing](tracing.mdx) for more details.
+:::
+
+```python
+from zepben.evolve import Terminal, PhaseCode
+# Example of setting nominal phases on a terminal
+Terminal terminal = Terminal(phases=PhaseCode.ABC)
+```
+
+## Grouping equipment
+
+In electricity distribution networks, a model is typically made up of groups of equipment that represent different
+sections of the network. For example things like: feeder, zone (substation), transmission line etc. The terminology 
+differs within the industry, however CIM provides types of 
+[EquipmentContainer](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/EquipmentContainer) to allow you to
+group equipment into the above types of categories. You can refer to the Evolve profile CIM profile for all supported equipment 
+container types in the model, however the most common ones are:
+
+- [Line](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Wires/Line/)
+- [Substation](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/Substation/)
+- [Feeder](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/Feeder/)
+
+### Network Hierarchy
+
+When creating a `Substation` you will see that it can belong to a 
+[SubGeographicalRegion](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/SubGeographicalRegion) and a
+`SubGeogrpahicalRegion` can belong to a 
+[GeographicalRegion](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/GeographicalRegion).
+
+When using various parts of the Evolve platform, it will refer to the concept of a network hierarchy. This is the 
+mechanism used to chunk up the network and provides an overview of what makes up the model. The network hierarchy looks
+as follows:
+
+* GeographicalRegion
+  * SubGeographicalRegion
+    * Substation
+      * Feeder
+
+When working with the Evolve Platform, it is important to make sure equipment and equipment containers are correctly
+populated as there are assumptions built around the network being structured in this pattern.
+
+### Feeders
+
+A feeder is generally a chain of equipment from a nominated starting point in a `Substation` to all open points when 
+tracing along the equipment. The starting point can be defined by setting a 
+[Feeder's](https://zepben.github.io/evolve/docs/cim/evolve/IEC61970/Base/Core/Feeder/) `normal_head_terminal`. This means if you
+have a correctly connected model, setting the feeder equipment container on any equipment can be calculated dynamically. 
+This has the benefit of making sure that an equipment's feeder is always correct (because it has been set by checking
+connectivity). A function to do this is provided as part of the [tracing](tracing.mdx#useful-traces) package.
+
+### Example
+
+The following example shows how you can build a network hierarchy and assign equipment to their appropriate equipment
+containers.
+
+```python
+from zepben.evolve import GeographicalRegion, SubGeographicalRegion, PowerTransformer, Feeder, Breaker
+
+region = GeographicalRegion()
+sub_region = SubGeographicalRegion(geographical_region=region)
+region.add_sub_geographical_region(sub_region)
+
+substation = Substation(sub_geographical_region=sub_region)
+
+sub_tx = PowerTransformer()
+sub_tx.add_container(substation)
+substation.add_equipment(sub_tx)
+
+feeder = Feeder(normal_energizing_substation=substation)
+
+feeder_cb = Breaker()
+feeder_cb.add_container(feeder)
+feeder.add_equipment(this)
+```
+
+---