[OPS-499] Move docs to build with Docusaurus3

docs/.gitignore

@@ -0,0 +1,5 @@
+# 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.2.0/network_service_interactions.mdx → docs/archive/versioned_docs/version-0.2.0/network_service_interactions.mdx

@@ -120,14 +120,14 @@ Output:
 
 You can use the `objects` method to iterate over all objects that inherit a specified type.
 In this example, we will query the objects from the network based on their types. From the above example, the network consists of a Breaker and an AcLineSegment.
-Let us query the object based on the type Switch. Since a Breaker is the only object in the network model that inherits from the `Switch` class, the following must print "Switch: Breaker{b_456}".
+Let us query the object based on the type Switch. Since a Breaker is the only object in the network model that inherits from the `Switch` class, the following must print "Switch: Breaker\{b_456\}".
 
 ```python
 for switch in network.objects(Switch):
     print(f"Switch: {switch}")
 ```
 
-However, since both the Breaker and the AcLineSegment inherit from `ConductingEquipment`, the following must print "Conducting equipment: AcLineSegment{acls_123}" and "Conducting equipment: Breaker{b_456}".
+However, since both the Breaker and the AcLineSegment inherit from `ConductingEquipment`, the following must print "Conducting equipment: AcLineSegment\{acls_123\}" and "Conducting equipment: Breaker\{b_456\}".
 
 ```python
 for conducting_equipment in network.objects(ConductingEquipment):

docs/versioned_docs/version-0.5.0/network_service_interactions.mdx → docs/archive/versioned_docs/version-0.5.0/network_service_interactions.mdx

@@ -120,14 +120,14 @@ Output:
 
 You can use the `objects` method to iterate over all objects that inherit a specified type.
 In this example, we will query the objects from the network based on their types. From the above example, the network consists of a Breaker and an AcLineSegment.
-Let us query the object based on the type Switch. Since a Breaker is the only object in the network model that inherits from the `Switch` class, the following must print "Switch: Breaker{b_456}".
+Let us query the object based on the type Switch. Since a Breaker is the only object in the network model that inherits from the `Switch` class, the following must print "Switch: Breaker\{b_456\}".
 
 ```python
 for switch in network.objects(Switch):
     print(f"Switch: {switch}")
 ```
 
-However, since both the Breaker and the AcLineSegment inherit from `ConductingEquipment`, the following must print "Conducting equipment: AcLineSegment{acls_123}" and "Conducting equipment: Breaker{b_456}".
+However, since both the Breaker and the AcLineSegment inherit from `ConductingEquipment`, the following must print "Conducting equipment: AcLineSegment\{acls_123\}" and "Conducting equipment: Breaker\{b_456\}".
 
 ```python
 for conducting_equipment in network.objects(ConductingEquipment):

docs/versioned_docs/version-0.6.0/network_service_interactions.mdx → docs/archive/versioned_docs/version-0.6.0/network_service_interactions.mdx

@@ -120,14 +120,14 @@ Output:
 
 You can use the `objects` method to iterate over all objects that inherit a specified type.
 In this example, we will query the objects from the network based on their types. From the above example, the network consists of a Breaker and an AcLineSegment.
-Let us query the object based on the type Switch. Since a Breaker is the only object in the network model that inherits from the `Switch` class, the following must print "Switch: Breaker{b_456}".
+Let us query the object based on the type Switch. Since a Breaker is the only object in the network model that inherits from the `Switch` class, the following must print "Switch: Breaker\{b_456\}".
 
 ```python
 for switch in network.objects(Switch):
     print(f"Switch: {switch}")
 ```
 
-However, since both the Breaker and the AcLineSegment inherit from `ConductingEquipment`, the following must print "Conducting equipment: AcLineSegment{acls_123}" and "Conducting equipment: Breaker{b_456}".
+However, since both the Breaker and the AcLineSegment inherit from `ConductingEquipment`, the following must print "Conducting equipment: AcLineSegment\{acls_123\}" and "Conducting equipment: Breaker\{b_456\}".
 
 ```python
 for conducting_equipment in network.objects(ConductingEquipment):

docs/docs/network_service_interactions.mdx

@@ -120,14 +120,14 @@ Output:
 
 You can use the `objects` method to iterate over all objects that inherit a specified type.
 In this example, we will query the objects from the network based on their types. From the above example, the network consists of a Breaker and an AcLineSegment.
-Let us query the object based on the type Switch. Since a Breaker is the only object in the network model that inherits from the `Switch` class, the following must print "Switch: Breaker{b_456}".
+Let us query the object based on the type Switch. Since a Breaker is the only object in the network model that inherits from the `Switch` class, the following must print "Switch: Breaker\{b_456\}".
 
 ```python
 for switch in network.objects(Switch):
     print(f"Switch: {switch}")
 ```
 
-However, since both the Breaker and the AcLineSegment inherit from `ConductingEquipment`, the following must print "Conducting equipment: AcLineSegment{acls_123}" and "Conducting equipment: Breaker{b_456}".
+However, since both the Breaker and the AcLineSegment inherit from `ConductingEquipment`, the following must print "Conducting equipment: AcLineSegment\{acls_123\}" and "Conducting equipment: Breaker\{b_456\}".
 
 ```python
 for conducting_equipment in network.objects(ConductingEquipment):