From 23cfbecb7e6debff570c312182736aac7050ac16 Mon Sep 17 00:00:00 2001
From: Jorrit Nutma <jorrit.nutma@tno.nl>
Date: Thu, 17 Apr 2025 16:17:51 +0200
Subject: [PATCH 1/3] update README

---
 README.md | 40 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 37 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index a4ea133..ccfcb61 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,43 @@
 </div>
 <br />
 
-This repository contains the source code for the [documentation website for the S2 standard](https://flexiblepower.github.io/s2-documentation/), plus the structured documentation that website is generated from.
+See the live version at [docs.s2standard.org](https://docs.s2standard.org).
+
+This repository contains the source code for the documentation website of the S2 standard. Additionally, it includes the structured documentation from which the data model reference is generated. 
+
+> The structured documentation serves as the single source of truth for other places where the data model is documented, such as in the S2-Rust library.
+
 
 ## Workflow
-For the initial generation of the structured documentation, you can use the `structured-documentation-generator`. The idea is that the initial files are generated, and are then hand-edited to further improve them and add more documentation. This means you'll only generate them once, and never regenerate them. The data model for the structured documentation is contained in [`structured-documentation-generator/src/doc_types.rs`](structured-documentation-generator/src/doc_types.rs).
 
-`website-generator` takes the structured documentation and generates Markdown files for them, which are placed in `website/docs/API`. `website` contains the file that make up the actual documentation website. These are built and deployed to the `deployment` branch, which is used by Github Pages to serve the website.
\ No newline at end of file
+### Generate structure documentation (one time action)
+For the initial generation of the structured documentation, the `structured-documentation-generator` has been used. This is a one time action, i.e. the structured documentation has been generated once, and should not be regenerated again. The data model for the structured documentation is contained in [`structured-documentation-generator/src/doc_types.rs`](structured-documentation-generator/src/doc_types.rs). The result has been put in the `structured-documentation` folder.
+
+### Document the data model
+The generated structured documentation from the previous step is the starting point for the documentation of the data model. The documentation has to be extended manually.
+
+### Generate Markdown for data model reference
+The data model reference is created directly from the structured-documentation. Since Docusaurus allows for Markdown-based documentation, the `website-generator` takes the structured documentation and generates Markdown files for them, which are placed in `website/model-reference`. Please note that this folder is added to `.gitignore` because the Markdown files will be freshly created during the deployment. 
+
+### Write documentation for S2
+The `website` directory contains the file that make up the actual documentation website. Please find in the `website/docs` directory all the Markdown files that constitute the documentation of the S2 standard. The convention is to follow pretty URL patterns (i.e. kebab-case) for the directories and filenames because Docusaurus uses those names to create URLs to the pages (and we want pretty URLs, of course).
+
+### Running the documentation development server
+Docusaurus comes with a development server with hot-code replacement. To build the documentation website and to run the development server locally, make sure to have nodejs (v. 18 and higher) installed, and run from the `website` directory:
+
+```
+npm run start
+```
+
+Sometimes it is needed to clear the build cache in case there are errors displayed on the development website:
+
+```
+npm run clear
+```
+
+
+### Deployment
+The documentation website is deployed to GitHub pages with GitHub actions. Every time a branch is merged to master, the website is automatically deployed 🚀
+
+## Technical details
+The documentation website is created by means of [docusaurus.io](https://docusaurus.io/), that leverages React to create powerful websites but also allows for easy-to-write Markdown-based documentation. "This project uses the default styling theme of Docusaurus that uses [infima](https://infima.dev/). So if you want to style something on the main page, please refer to the infima docs.
\ No newline at end of file

From 421402078cb483e52dbe02c5bb6aaf08ac71579b Mon Sep 17 00:00:00 2001
From: Jorrit Nutma <jorrit.nutma@tno.nl>
Date: Thu, 17 Apr 2025 16:21:38 +0200
Subject: [PATCH 2/3] remove deploy task in Justfile as deployment is covered
 by GitHub actions

---
 Justfile | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Justfile b/Justfile
index 166703a..1a70529 100644
--- a/Justfile
+++ b/Justfile
@@ -6,6 +6,3 @@ generate-structured-documentation:
 
 generate-website:
     cd website-generator && cargo run --release
-
-deploy:
-    cd website && npm run deploy
\ No newline at end of file

From 759ef09ce1b2fb3b9f14876c1aef82efd4212fa2 Mon Sep 17 00:00:00 2001
From: Jorrit Nutma <jorrit.nutma@tno.nl>
Date: Wed, 23 Jul 2025 17:01:22 +0200
Subject: [PATCH 3/3] Add newlines in the state-of-communication table with
 message overview

---
 .../state-of-communication.md                      | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/website/docs/s2-json-over-websockets/state-of-communication.md b/website/docs/s2-json-over-websockets/state-of-communication.md
index 3d6e337..92e98a4 100644
--- a/website/docs/s2-json-over-websockets/state-of-communication.md
+++ b/website/docs/s2-json-over-websockets/state-of-communication.md
@@ -9,10 +9,10 @@ title: "States of Communication"
 
 | State | Messages that can be sent by CEM /received by RM | Messages that can be sent by RM / received by CEM |
 | --- | --- | --- |
-| WebSocket Connected | Handshake HandshakeResponse ReceptionStatus | Handshake ReceptionStatus |
-| Initialized | SelectControlType SessionRequest ReceptionStatus | ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus |
-| ControlType PEBC activated | PEBC.Instruction SelectControlType SessionRequest ReceptionStatus | PEBC.EnergyConstraint PEBC.PowerConstraint RevokeObject InstructionStatusUpdate ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus |
-| ControlType PPBC activated | PPBC.EndInterrptionInstruction PPBC.ScheduleInstruction PPBC.StartInterruptionInstruction SelectControlType SessionRequest ReceptionStatus | PPBC.PowerProfileDefinition PPBC.PowerPorfileStatus RevokeObject InstructionStatusUpdate ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus |
-| ControlType OMBC activated | OMBC.Instruction SelectControlType SessionRequest ReceptionStatus | OMBC.Status OMBC.SystemDescription OMBC.TimerStatus RevokeObject InstructionStatusUpdate ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus |
-| ControlType FRBC activated | FRBC.Instruction SelectControlType SessionRequest ReceptionStatus | FRBC.ActuatorStatus FRBC.FillLevelTargetProfile FRBC.LeakageBehaviour FRBC.StorageStatus FRBC.SystemDescription FRBC.UsageForecast FRBC.TimerStatus RevokeObject InstructionStatusUpdate ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus |
-| ControlType DDBC activated | DDBC.Instruction SelectControlType SessionRequest ReceptionStatus | DDBC.ActuatorStatus DDBC.AverageDemandRateForecast DDBC.SystemDescription DDBC.TimerStatus RevokeObject InstructionStatusUpdate ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus |
\ No newline at end of file
+| WebSocket Connected | Handshake <br/> HandshakeResponse <br/> ReceptionStatus | Handshake <br/> ReceptionStatus |
+| Initialized | SelectControlType <br/> SessionRequest <br/> ReceptionStatus | ResourceManagerDetails <br/> PowerMeasurement <br/> PowerForecast <br/> SessionRequest <br/> ReceptionStatus |
+| ControlType PEBC activated | PEBC.Instruction <br/> SelectControlType <br/> SessionRequest <br/> ReceptionStatus | PEBC.EnergyConstraint <br/> PEBC.PowerConstraint <br/> RevokeObject <br/> InstructionStatusUpdate <br/> ResourceManagerDetails <br/> PowerMeasurement <br/> PowerForecast <br/> SessionRequest <br/> ReceptionStatus |
+| ControlType PPBC activated | PPBC.EndInterrptionInstruction <br/> PPBC.ScheduleInstruction <br/> PPBC.StartInterruptionInstruction <br/> SelectControlType <br/> SessionRequest <br/> ReceptionStatus | PPBC.PowerProfileDefinition <br/> PPBC.PowerPorfileStatus <br/> RevokeObject InstructionStatusUpdate <br/> ResourceManagerDetails <br/> PowerMeasurement <br/> PowerForecast <br/> SessionRequest <br/> ReceptionStatus |
+| ControlType OMBC activated | OMBC.Instruction <br/> SelectControlType <br/> SessionRequest <br/> ReceptionStatus | OMBC.Status <br/> OMBC.SystemDescription <br/> OMBC.TimerStatus <br/> RevokeObject <br/> InstructionStatusUpdate <br/> ResourceManagerDetails <br/> PowerMeasurement <br/> PowerForecast <br/> SessionRequest <br/> ReceptionStatus |
+| ControlType FRBC activated | FRBC.Instruction <br/> SelectControlType <br/> SessionRequest <br/> ReceptionStatus | FRBC.ActuatorStatus <br/> FRBC.FillLevelTargetProfile <br/> FRBC.LeakageBehaviour <br/> FRBC.StorageStatus <br/> FRBC.SystemDescription <br/> FRBC.UsageForecast <br/> FRBC.TimerStatus <br/> RevokeObject <br/> InstructionStatusUpdate <br/> ResourceManagerDetails <br/> PowerMeasurement <br/> PowerForecast <br/> SessionRequest <br/> ReceptionStatus |
+| ControlType DDBC activated | DDBC.Instruction <br/> SelectControlType <br/> SessionRequest <br/> ReceptionStatus | DDBC.ActuatorStatus <br/> DDBC.AverageDemandRateForecast <br/> DDBC.SystemDescription <br/> DDBC.TimerStatus <br/> RevokeObject <br/> InstructionStatusUpdate <br/> ResourceManagerDetails <br/> PowerMeasurement <br/> PowerForecast <br/> SessionRequest <br/> ReceptionStatus |
\ No newline at end of file