feat(docs): restructure OCHP documentation by adding preface, version…

…ing, conventions, and abbreviations sections to enhance clarity and usability

feat(docs): implement CH-partner interface description to detail data exchange processes between partners and the clearing house
feat(docs): add Algolia search integration to improve documentation navigation and user experience
style(docs): update custom CSS for improved styling of search components in light and dark themes

site/docs/protocols/ochp/_category_.json

@@ -1,12 +1,5 @@
 {
   "label": "OCHP",
   "collapsible": true,
-  "collapsed": true,
-  "link": {
-    "type": "generated-index",
-    "title": "OCPH - Open Clearing House Protocol"
-  },
-  "customProps": {
-    "description": "Open Clearing House Protocol"
-  }
+  "collapsed": true
 }

site/docs/protocols/ochp/ochp/preface/preface.md → site/docs/protocols/ochp/ochp/00-preface/01-preface.md

@@ -1,5 +1,7 @@
 ---
 sidebar_position: 1
+slug: /protocols/ochp/ochp/preface
+id: preface
 ---
 # Preface
 

site/docs/protocols/ochp/ochp/00-preface/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "Preface",
+  "position": 1,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "doc",
+    "id": "preface"
+  }
+}

site/docs/protocols/ochp/ochp/abbreviations/abbreviations.md → site/docs/protocols/ochp/ochp/01-abbreviations/01-abbreviations.md

@@ -1,3 +1,7 @@
+---
+slug: /protocols/ochp/ochp/abbreviations
+id: abbreviations
+---
 # Abbreviations
 
 | Abbreviation |                    Meaning                     |

site/docs/protocols/ochp/ochp/01-abbreviations/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "Abbreviations",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "doc",
+    "id": "abbreviations"
+  }
+}

site/docs/protocols/ochp/ochp/introduction/primary-stakeholders-electric-vehicles.md → site/docs/protocols/ochp/ochp/02-introduction/01-primary-stakeholders-electric-vehicles.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 1
+id: primary-stakeholders-electric-vehicles
 ---
 # Primary Stakeholders Electric Vehicles
 

site/docs/protocols/ochp/ochp/02-introduction/03-clearing-house-functionality.md

@@ -0,0 +1,31 @@
+---
+sidebar_position: 4
+---
+# Clearing House functionality
+
+An EV clearing house in the scope of this protocol facilitates the
+mutual exchange of roaming authorisations, charge data & charge point
+information between its partners. The formal act of clearing - as meant
+here - is the assignment of charge detail records to the corresponding
+EV Service Provider. The financial clearing has to be executed in a
+subsequent process step and is out of scope of the interface addressed
+by OCHP. However, the here defined data types are meant to be used as a
+base to calculate the payment request.
+Normally the following steps are followed, (*highlighted* steps are
+in scope of OCHP):
+
+* *An EVSP (Partner A) uploads authorisation data of its EV users to 
+  the Clearing House (CH).*
+* *The EVSE operators that have a roaming contract with (A), download 
+  this authorisation data from the CH.*
+* The EVSE operators enable these authorisations to be used on their 
+  charge points.
+* The EV users of partner (A) can now charge their electric vehicles 
+  at all charge points of the EVSE operators named in step 2.
+* *The EVSE operator uploads the charge data (using Charge Detail 
+  Records) to the CH.*
+* *This charge data is then routed by the CH towards partner (A) using 
+  OCHP.*
+* Partner (A) pays the roaming partner for the charging action done by 
+  its customer.
+* Partner (A) bills its customer.

site/docs/protocols/ochp/ochp/introduction/ochpdirect-extension.md → site/docs/protocols/ochp/ochp/02-introduction/05-ochpdirect-extension.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 # OCHPdirect Extension
 

site/docs/protocols/ochp/ochp/introduction/_category_.json → site/docs/protocols/ochp/ochp/02-introduction/_category_.json

@@ -1,5 +1,6 @@
 {
   "label": "Introduction",
+  "position": 3,
   "collapsible": true,
   "collapsed": true
 }

site/docs/protocols/ochp/ochp/03-ch-partner-interface-description/01-primary-stakeholders-electric-vehicles.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 1
+id: ch-partner-interface-description
+---
+# CH-Partner Interface description
+
+The interfaces between the system of the Clearing House and systems of
+the different partners consist of the six following components:
+
+* Exchange of Authorisation Data (Roaming Authorisations, 
+  RoamingAuthorisationInfo)
+* Exchange of Charge Data, the raw billing data (Charge Detail 
+  Records, CDRInfo)
+* Exchange of Charge Point Information (Static and live POI data, 
+  ChargePointInfo)
+* Exchange of Tariff Information (TariffInfo)
+* Single Authorization Requests (Single-Token-Requests)
+* Exchange of Parking Spot Information (Static and live data)
+
+From the data flow perspective, each market role is a source or a sink
+for certain data types. The figure below gives an overview of
+the exchanged data types, their direction and their particular
+originating and consuming market role.
+
+![Figure Data flow and direction overview](../../media/DataFlows.png "Data flow and direction overview")
+
+The exchange of data takes place via standardized web services.
+

site/docs/protocols/ochp/ochp/03-ch-partner-interface-description/02-exchange-authorisation-data.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 1
+id: exchange-authorisation-data
+---
+# Exchange Authorisation Data
+
+## Upload own authorisation data (roaming list) to the CHS
+
+The MDM of each EVSP has to exchange the own authorisation data with the
+Clearing House to share that data with EVSE Operators. The upload of the
+own roaming list is done in the following way:
+
+* MDM sends the SetRoamingAuthorisationList.req PDU.
+* CHS responds with a SetRoamingAuthorisationList.conf PDU.
+
+## Update own authorisation data (roaming list) in the CHS
+
+For later updates of authorization data from the MDM to the Clearing
+House and the EVSE Operators, only the changed entries (delta) have to
+be transferred. The updated roaming list entries have to be sent the
+following way:
+
+* MDM sends the UpdateRoamingAuthorisationList.req PDU.
+* CHS responds with a UpdateRoamingAuthorisationList.conf PDU.
+
+## Download global roaming authorisation data from CHS
+
+A CMS downloads the global authorisation data repository from the CHS.
+The download of the global roaming list is done in the following way:
+
+* CMS sends the GetRoamingAuthorisationList.req PDU.
+* CHS responds with GetRoamingAuthorisationList.conf PDU.
+
+## Download updates in global roaming authorisation data from CHS
+
+A CMS downloads the changes to the global authorisation data repository
+since the last synchronization from the CHS. The updates in the global
+roaming list can be done in the following way:
+
+* CMS sends the GetRoamingAuthorisationListUpdates.req PDU.
+* CHS responds with GetRoamingAuthorisationListUpdates.conf PDU.

site/docs/protocols/ochp/ochp/03-ch-partner-interface-description/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "CH-Partner Interface description",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "doc",
+    "id": "ch-partner-interface-description"
+  }
+}

site/docs/protocols/ochp/ochp/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "OCHP",
+  "collapsible": true,
+  "collapsed": true
+}

site/docusaurus.config.ts

@@ -79,6 +79,41 @@ const config: Config = {
   ],
 
   themeConfig: {
+
+    algolia: {
+      // The application ID provided by Algolia
+      appId: '2ZN1WIJPX8',
+
+      // Public API key: it is safe to commit it
+      apiKey: '60c1c07854fb7dabe1c6887c1a949318',
+
+      indexName: 'YOUR_INDEX_NAME',
+
+      // Optional: see doc section below
+      contextualSearch: true,
+
+      // Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them.
+      externalUrlRegex: 'external\\.com|domain\\.com',
+
+      // Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs
+      replaceSearchResultPathname: {
+        from: '/docs/', // or as RegExp: /\/docs\//
+        to: '/',
+      },
+
+      // Optional: Algolia search parameters
+      searchParameters: {},
+
+      // Optional: path for search page that enabled by default (`false` to disable it)
+      searchPagePath: 'search',
+
+      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
+      insights: false,
+
+      //... other Algolia params
+    },
+
+
     // Replace with your project's social card
     image: 'img/docusaurus-social-card.jpg',
     navbar: {

site/package.json

@@ -19,6 +19,7 @@
     "@docusaurus/plugin-google-gtag": "^3.5.2",
     "@docusaurus/plugin-sitemap": "^3.5.2",
     "@docusaurus/preset-classic": "3.5.2",
+    "@docusaurus/theme-search-algolia": "^3.5.2",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",

site/src/css/custom.css

@@ -28,3 +28,43 @@
   --ifm-color-primary-lightest: #4fddbf;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }
+
+[data-theme='light'] .DocSearch {
+  /* --docsearch-primary-color: var(--ifm-color-primary); */
+  /* --docsearch-text-color: var(--ifm-font-color-base); */
+  --docsearch-muted-color: var(--ifm-color-secondary-darkest);
+  --docsearch-container-background: rgba(94, 100, 112, 0.7);
+  /* Modal */
+  --docsearch-modal-background: var(--ifm-color-secondary-lighter);
+  /* Search box */
+  --docsearch-searchbox-background: var(--ifm-color-secondary);
+  --docsearch-searchbox-focus-background: var(--ifm-color-white);
+  /* Hit */
+  --docsearch-hit-color: var(--ifm-font-color-base);
+  --docsearch-hit-active-color: var(--ifm-color-white);
+  --docsearch-hit-background: var(--ifm-color-white);
+  /* Footer */
+  --docsearch-footer-background: var(--ifm-color-white);
+}
+
+[data-theme='dark'] .DocSearch {
+  --docsearch-text-color: var(--ifm-font-color-base);
+  --docsearch-muted-color: var(--ifm-color-secondary-darkest);
+  --docsearch-container-background: rgba(47, 55, 69, 0.7);
+  /* Modal */
+  --docsearch-modal-background: var(--ifm-background-color);
+  /* Search box */
+  --docsearch-searchbox-background: var(--ifm-background-color);
+  --docsearch-searchbox-focus-background: var(--ifm-color-black);
+  /* Hit */
+  --docsearch-hit-color: var(--ifm-font-color-base);
+  --docsearch-hit-active-color: var(--ifm-color-white);
+  --docsearch-hit-background: var(--ifm-color-emphasis-100);
+  /* Footer */
+  --docsearch-footer-background: var(--ifm-background-surface-color);
+  --docsearch-key-gradient: linear-gradient(
+    -26.5deg,
+    var(--ifm-color-emphasis-200) 0%,
+    var(--ifm-color-emphasis-100) 100%
+  );
+}