Restructuring documentation to enable website generation (#509)

* Add initial version of docs for website

* Enabled plugin for (local) search functionality

* Cleaned up settings & added Tabs & Syntax Highlighting for Code Blocks

* Minor textual improvements & using Tabs for Reasoning page

* Create Github Action for deployment of documentation website

.github/workflows/docs-deployment.yml

@@ -0,0 +1,32 @@
+name: Deploy documentation website
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - docs/**
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Install Node.js
+        uses: actions/setup-node@master
+      - name: Install dependencies
+        working-directory: ./docs
+        run: npm install
+      - name: Build documentation website
+        working-directory: ./docs
+        run: npm run build
+      - name: Install SSH Key
+        uses: shimataro/ssh-key-action@v2
+        with:
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          known_hosts: 'placeholder'
+      - name: Add known hosts
+        run: ssh-keyscan -H ${{ secrets.SSH_HOST }} >> ~/.ssh/known_hosts
+      - name: Deploy to server
+        working-directory: ./docs
+        run: scp -r build/* ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:${{ secrets.SSH_DOCS_PATH }}

README.md

@@ -4,7 +4,7 @@
 
 [![DOI](https://zenodo.org/badge/502097185.svg)](https://zenodo.org/badge/latestdoi/502097185)
 
-[![Knowledge Engine logo](./docs/img/ke_text_white_backdrop.png)](https://www.knowledge-engine.eu/)
+[![Knowledge Engine logo](docs/static/img/ke_text_white_backdrop.png)](https://www.knowledge-engine.eu/)
 
 Welcome to the source code repository of the Knowledge Engine.
 This README should help you understand what the Knowledge Engine is, and how to use it.
@@ -181,7 +181,7 @@ This section gives more detailed information about the project's structure, and
 
 The Knowledge Engine project consists of the following Maven modules:
 - `smart-connector`
-  - This is the implementation of the smart connector, with the Java developer API. For instructions on how to use it, refer to [the documentation](./docs/03_java_developer_api.md).
+  - This is the implementation of the smart connector, with the Java developer API. For instructions on how to use it, refer to [the documentation](./docs/docs/java_developer_api.md).
 - `smart-connector-api`
 	- This module contains interfaces for the smart connector and other classes. It is made as a separate module so that it is easy to use different implementations of the interfaces.
 - `smart-connector-rest-server`
@@ -256,7 +256,7 @@ nohup java -cp "smart-connector-rest-dist-1.2.4.jar:dependency/*" eu.knowledge.e
 ```
 
 ### Starting the Knowledge Engine in distributed mode
-The Knowledge Engine can also start in distributed mode, where it connects with a remote knowledge directory and where different instances of the Knowledge Engine (each instance hosting one or more smart connectors) can communicate with each other. More information about starting the Knowledge Engine in distributed mode can be found in the [documentation](docs/04_distributed_mode.md).
+The Knowledge Engine can also start in distributed mode, where it connects with a remote knowledge directory and where different instances of the Knowledge Engine (each instance hosting one or more smart connectors) can communicate with each other. More information about starting the Knowledge Engine in distributed mode can be found in the [documentation](docs/docs/distributed_mode.md).
 
 ### Additional configuration environment variables
 

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*

docs/README.md

@@ -0,0 +1,34 @@
+# Documentation
+
+This directory contains the documentation for the Knowledge Engine as well as the required settings that are used to generate the documentation website.
+The documentation can be found in the `docs/` directory.
+
+
+## Generating the website
+
+Required:
+- [Node.js](https://nodejs.org/en/download/) version 18.0 or above:
+  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
+
+### Generate website files
+To statically generate the website, within this directory (`knowledge-engine/docs/`), run:
+```bash
+npm run build
+```
+This will generate a `build/` directory containing all files for the website.
+
+Be careful when editing code blocks with tabs.
+Currently, it requires you to leave empty lines around the Markdown syntax
+
+
+
+### Test the site locally
+
+If you're working on the documentation, you can locally run a serve so you can easily see what your changes look like.
+To run the development server, within this directory (`knowledge-engine/docs/`), execute:
+```bash
+npm run start
+```
+
+The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
+The site will **automatically reload** and display your changes.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/01_concept.md → docs/docs/conceptual_framework.md

@@ -1,3 +1,7 @@
+---
+ sidebar_position: 2
+---
+
 # Conceptual Framework
 
 This section explains the ideas behind the Knowledge Engine.
@@ -18,7 +22,7 @@ However, much power lies in *combining* several of these knowledge bases (explai
 
 An important assumption that we make is that a knowledge base can be sufficiently described in terms of the knowledge that it processes.
 This means that we can describe what kind of knowledge can be extracted from this base and what kind of knowledge this base is interested in, and that we capture this well enough to provide synergy to the network.
-In other words, we assume that we can make a description of the knowledge base that captures its knowledge input and output ([knowledge Interaction](#knowledge-interaction)): What knowledge does it provide? What knowledge does it require?
+In other words, we assume that we can make a description of the knowledge base that captures its knowledge input and output ([Knowledge Interaction](#knowledge-interaction)): What knowledge does it provide? What knowledge does it require?
 Furthermore, we assume that we capture the knowledge interactions of a knowledge base well enough that it can be exploited or satisfied by *other* knowledge bases.
 
 It is important to note that knowledge bases aren't limited to being *just* producers or consumers of information; they could trigger **side effects**, and thus play a role in control systems such as heating systems or artificial cardiac pacemakers.
@@ -48,11 +52,11 @@ To their surprise, it is now necessary to install another app!
 In the example above, there were three physical devices: The phone and the two light bulbs.
 However, the phone contained two 'knowledge bases' and the knowledge for both light bulb systems was completely siloed:
 
-![two apps talking a different protocol to different lamps](./img/silos.png)
+![two apps talking a different protocol to different lamps](../static/img/silos.png)
 
 It would be convenient if the silos exchanged information, or better, if there was a single generic app that can communicate with both bulbs:
 
-![one app that can talk to both light bulbs, using the other app as an intermediary](./img/exchanging.png)
+![one app that can talk to both light bulbs, using the other app as an intermediary](../static/img/exchanging.png)
 
 Because of these obvious advantages, combining knowledge bases like this is becoming increasingly common.
 Currently, these combinations are often hand-made, and it would be convenient to make this easier.
@@ -68,7 +72,7 @@ This is solved by smart connectors.
 A smart connector is an entity (currently in the form of a Java object) that allows a knowledge base to register with the knowledge network, and exchange knowledge with it.
 It represents the knowledge base within the knowledge network, and acts on its behalf.
 
-In the registration phase, the knowledge base has to specify how it wants to exchange what knowledge (the [knowledge Interaction](#knowledge-interaction)):
+In the registration phase, the knowledge base has to specify how it wants to exchange what knowledge (the [Knowledge Interaction](#knowledge-interaction)):
 
 - What knowledge can be requested from me?
 - What knowledge will I publish to the network?
@@ -85,11 +89,11 @@ In the exchange phase, knowledge is consumed, produced, or published by the know
 A requirement for being able to use smart connectors in a domain is that all knowledge bases need to agree on a common language to exchange their knowledge in.
 This language is different for every domain.
 (In the thermostat example above, this language should include concepts like measurements, temperature, and preferences.)
-In the knowledge engine, this language can be expressed in the form of an ontology or knowledge model, which is explained further in [a following section](#knowledge-model).
+In the Knowledge Engine, this language can be expressed in the form of an ontology or knowledge model, which is explained further in [a following section](#knowledge-model).
 
 The domain's knowledge model is written in RDF/OWL, which allows us to take advantage of the reasoning capabilities that are available for these models.
 
-Since the knowledge engine internally knows about the supply and demand of knowledge in the network, it can use reasoning to orchestrate of knowledge supply on-demand.
+Since the Knowledge Engine internally knows about the supply and demand of knowledge in the network, it can use reasoning to orchestrate of knowledge supply on-demand.
 
 Critically, this means that, given a specification of knowledge that is requested, a smart connector **can figure out for you where to get it**!
 The developer of a knowledge base doesn't have to know or care about the specifics of all other knowledge bases.
@@ -101,11 +105,11 @@ The main advantages of using smart connectors are:
 - Changes in the knowledge network are handled seamlessly by synchronizing information about knowledge interactions.
 - Established open-source Semantic Web technologies are leveraged to provide knowledge models and reasoning capabilities.
 
-## Dynamic knowledge network
+## Dynamic Knowledge Network
 
 As long as the smart connectors are aware of changes in the network, new knowledge bases can be dynamically added to the network.
 
-Information about the [knowledge Interactions](#knowledge-interaction) of smart connectors is synchronized by using a [*knowledge directory*](#knowledge-directory), explained [further on](#knowledge-directory).
+Information about the [Knowledge Interactions](#knowledge-interaction) of smart connectors is synchronized by using a [*Knowledge Directory*](#knowledge-directory), explained [further on](#knowledge-directory).
 
 For example, we could add a smart curtain to the hypothetical home automation knowledge network that automatically closes the curtains when the lights in the same room are turned on after sunset.
 
@@ -167,35 +171,8 @@ The simple temperature sensor in the example is unable to store much data, so it
 
 Since all smart connectors need to know about each other to exchange knowledge, they need a way to know of each other. The current solution implements this with a centralized knowledge directory. The knowledge directory is aware of all KE runtimes. The KE runtimes communicate with each other to receive information about all smart connectors within a particular KE runtime.
 
-The Knowledge Engine runtimes can be started in distributive mode and non-distributive mode. In distributive mode, the KE runtime connects with a Knowledge Directory to discover other KE runtimes. In this mode, data exchange happens between smart connectors that live in any KE runtime that is registered with a particular Knowledge Directory. This is the preferred mode of the Knowledge Engine which is more decentralized because every actor hosts its own smart connector. More information about distributed mode can be found in the chapter on the [Distributed mode](04_distributed_mode.md).
-
-The knowledge engine can also be started in non-distributive mode in which it does not connect to a Knowledge Directory and also does not cooperate with other KE runtimes. In this mode, data exchange only happens between smart connectors that live in this single KE runtime. This mode is useful for getting started with the Knowledge Engine and for development and testing purposes.
-
-*Note: Developers using smart connectors do not need to know about the knowledge directory since the communication and synchronization is handled by the smart connectors internally.*
-
-## Rules
-
-<!-- TODO: Is information like this necessary for developers using smart connectors? They don't need to write rules, or do they? -->
-
-An if-then statement that tells the reasoner how to derive inferred facts from asserted facts. There are many forms of reasoning, but backward reasoning and forward reasoning are the typical ones. Backward reasoning means reasoning to prove a certain statement (i.e. question). This is also called goal-based reasoning, because you reason towards a particular goal (or actually, from a goal backwards to the actual data). Forward reasoning is also called data-driven reasoning, because it starts from the data and tries to infer all possible facts from this data using the available rules.
-
-## Security
-
-*__General direction Knowledge Engine security__*
-
-Within the KE we distinguish between several parts of the security question and explain below how we expect to deal with those:
-
-1) **connection between Knowledge Base (KB) and Smart Connector (SC)**: When using _Java_ Developer API this is secure by default, however, when using the REST Developer API we need to be more careful. The Generic Adapter and Service Store already provide some solution for this.
-2) **connection between SC and SC** (when in different Java Virtual Machines): By using a configurable Exposed URL (see [issue](https://gitlab.inesctec.pt/interconnect/knowledge-engine/-/issues/281)) the KE remains flexible with respect to the setup it is used in. This Exposed URL can point directly to the SC or to a proxy that is configured for HTTPS with certificates.
-3) **connection between SC and Knowledge Directory (KD)**: The Knowledge Directory itself exposes a REST API that we recommend to be put behind a HTTPS proxy. SCs have a configuration option to point to the URL of the Knowledge Directory. This can be both HTTP and HTTPS.
-4) **identification/authentication**: Still unclear, but we are thinking about *not* introducing the concept of a user within the KE. The reason is that the only way other KBs can really trust a user, is by having a centralized Identity Provider that all KBs can access which constrasts the distributed nature of the KE. But again, not sure about whether we can maintain this position. Sharing login credentials and JWT tokens through the KE by including them in the domain knowledge is of course possible and this indeed requires the ontologies to contain classes and properties related to login and token information.
-5) **authorization**: In the future we want to support roles and access control policies that are agreed upon by all KBs and it should make up the domain knowledge together with the ontology. We will definitely work on this in the future, but probably not in the scope of InterConnect.
-
-
-*__Sharing credentials__*
-
-As I mentioned in my previous comment there is no _right_ way to deal with sharing credentials. More discussion and experience is definitely necessary to find the sweet spot for security related issues like these. In your use cases, the easiest and safest way is probably to share the credentials outside of the Knowledge Engine and just use some token (or home id) in the graph pattern, but it might be interesting to see how actually sending the credentials through the KE works out using a login graph pattern. Keep in mind, though, that the KE does not encrypt anything by itself and that the credentials might be visible to others. 
+The Knowledge Engine runtimes can be started in distributive mode and non-distributive mode. In distributive mode, the KE runtime connects with a Knowledge Directory to discover other KE runtimes. In this mode, data exchange happens between smart connectors that live in any KE runtime that is registered with a particular Knowledge Directory. This is the preferred mode of the Knowledge Engine which is more decentralized because every actor hosts its own smart connector.
 
-## Mathematical framework
+The Knowledge Engine can also be started in non-distributive mode in which it does not connect to a Knowledge Directory and also does not cooperate with other KE runtimes. In this mode, data exchange only happens between smart connectors that live in this single KE runtime. This mode is useful for getting started with the Knowledge Engine and for development and testing purposes.
 
-The aim is to make a mathematical description of this framework, but for that we first need to stabilize our vision.
+*Note: Developers using smart connectors do not need to know about the Knowledge Directory since the communication and synchronization is handled by the Smart Connectors internally.*