Merge pull request #131 from openbase/feature/127-integrate-docs-into…

…-main-repo

Feature/127 integrate docs into main repo & changed to docusaurus

.github/workflows/build-and-test.yml

@@ -9,12 +9,54 @@ on:
     types: [opened, synchronize, reopened, ready_for_review]
 
 jobs:
-  build:
-    name: "Build"
-    timeout-minutes: 10
+  check:
+    name: "Check"
 
     if: github.event.pull_request.draft == false
 
+    runs-on: ubuntu-latest
+    outputs:
+      testing_needed: ${{ steps.check.outputs.testing_needed }}
+
+    steps:
+      - name: "Checkout Branch"
+        uses: actions/checkout@v3
+
+      ### Checks if there are any file changes that are not in the .github/ or doc/ directories
+      - name: "Check for changes outside CI and docs"
+        id: check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          changed_files=$(gh pr diff --name-only ${{ github.event.pull_request.number }})
+          
+          changesOutsideDocsCI=false
+          for file in $changed_files; do
+            if [[ $file -ne ".github/"* && $file -ne "doc/"* ]]; then
+              echo "file: $file is not part of CI or docs"
+              echo "Start testing pipeline."
+              changesOutsideDocsCI=true
+              break
+            else
+              echo "file: $file is part of CI or docs"
+            fi
+          done
+          if [[ $changesOutsideDocsCI == true ]]; then
+            echo "testing_needed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "testing_needed=false" >> "$GITHUB_OUTPUT"
+            echo "No need for the build and test pipeline to run. Exiting."
+          fi
+
+
+  build:
+    name: "Build"
+    timeout-minutes: 10
+    needs: check
+    if: |
+      (github.event.pull_request.draft == false)
+      && (needs.check.outputs.worth_testing == true)
+   
     runs-on: ubuntu-latest
 
     steps:
@@ -50,9 +92,10 @@ jobs:
   test:
     name: "Test"
     timeout-minutes: 120
-
-    if: github.event.pull_request.draft == false
     needs: build
+    if: |
+      (github.event.pull_request.draft == false)
+      && (needs.check.outputs.testing_needed == true)
 
     runs-on: ubuntu-latest
 
@@ -85,3 +128,4 @@ jobs:
         with:
           name: Test Reports
           path: "**/build/reports"
+

doc/.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*

doc/README.md

@@ -0,0 +1,33 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ pnpm install
+```
+
+### Local Development
+
+```
+$ pnpm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ pnpm build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+```
+$ pnpm serve
+```
+
+:::info INFO
+For the search to work locally, the website must be built using `pnpm build`
+:::

doc/babel.config.js

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

doc/docs/developer/README.md

@@ -0,0 +1,48 @@
+---
+---
+
+# Developer Section
+
+## Table Of Contents
+
+* [Developer Installation Guide](installation.md)
+* [System Startup and Tools](startup-tools.md)
+* [Directory Structure](directory-structure.md)
+* [Architecture](architecture.md)
+* [Authentication](authentication/README.md)
+* Contribution
+  * [How To Contribute](contribution.md)
+  * [Code Examples](code-examples.md)
+* [User Interfaces](ui/README.md)
+  * [BCozy](ui/bcozy.md): 2D Environment Control Map 
+  * [BComfy](ui/bcomfy.md): Augmented Reality Android App
+* Developer Interfaces
+  * [BCO Registry Editor](ui/bco-registry-editor.md): Tool to introspect, add, register and delete units, templates and class entries. 
+  * [BCO Stage](https://www.techfak.uni-bielefeld.de/csra/nightly/components/pointing_smart_control.html): 3D Environment Visualization
+  * [BCO Visual Remote](ui/bco-visual-remote.md): Generic control interface to access all services of a unit.
+  * [BCO Action Inspector](ui/bco-action-inspector.md): Used to make the current action - responsibilities visible.
+* Addons
+  * [PSC - Pointing Smart Control](addon/bco-psc.md): Control your environment via pointing gestures.
+  * [BCO Cloud](addon/bco-cloud.md): The bco cloud acts as gateway for third party integrations.
+  * [BCO Persistence](addon/bco-persistence.md): Addon to store the history of all service state changes.
+  * [BCO Ontology](addon/bco-ontology.md): The ontology is a fully synchronized semantic representation of the smart environment state.
+  * [Eveson - Event Sonification](addon/bco-eveson.md): An auditive display of your smart environment.
+* [Dependencies](dependencies.md)
+
+## Research Platforms
+
+### Cognitive Service Robotics Apartment
+
+* [Project Summary](https://www.cit-ec.de/en/csra)
+* [Project Details](https://cit-ec.de/de/cognitive-service-robotics-apartment-ambient-host)
+* [Documentation](http://www.techfak.uni-bielefeld.de/techfak/csra)
+* [BCO Setup Description](http://www.techfak.uni-bielefeld.de/techfak/csra/nightly/components/bco.html)
+
+:::info INFO
+Your research project is using Base Cube One but not listed here?
+We would love to know all details about it and support you during your development.
+Please [contact us](https://openbase.org/contact/) to get in touch.
+:::
+
+
+

doc/docs/developer/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Developer",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": { 
+    "type": "doc", "id": "README"
+  }
+}

doc/docs/developer/addon/bco-api-graphql.md

@@ -0,0 +1,72 @@
+# BCO GraphQL API
+
+[Source Code](https://github.com/openbase/bco.api.graphql)
+
+## Bonjour Service Advertising
+
+Service Name ```bco-api-graphql```
+
+## Default Settings
+* Suffix: ```graphql```
+* Port: ```13781```
+* Example Endpoint: ```http://localhost:13781/graphql```
+
+## Supported Queries
+* `login(username: String!, passwordHash: String!): String` - Retrieve an authentication token (see [Authorization Header](#supported-headers))
+  * Default admin base64 password hash: `R+gZ+PFuauhav8rRVa3XlWXXSEyi5BcdrbeXLEY3tDQ=`
+  * Checkout [how to generate the password hash on client side](#how-to-generate-the-password-hash-on-client-side) for more details. 
+* `verifyToken(token: String): Boolean`
+
+## Supported Mutations
+* `changePassword(username: String!, oldPassword: String!, newPassword: String!): Boolean` - Note: the return value will always be true since an exception is thrown if changing the password fails.
+* `updateLabel(unitId: String, label: String): Label` - Update the label of a unit. Note: this will update the first label considering the current language code which can be provided with the [Accept-Language Header](#supported-headers).
+* `updateLocation(unitId: String, locationId: String): PlacementConfig` - Update the location of a unit.
+* `updateFloorPlan(locationId: String, shape: Shape): Shape` - Clear the floor list of the current location and replace it with the list in the provided shape. Note: the rejoiner framework does not allow passing lists as arguments so you have to provide a complete shape from which only the floor list is considered.
+* `updatePose(unitId: String, pose: Pose): Pose` - Replace the pose of a unit.
+* `registerUnitConfig(unitConfig: UnitConfig): UnitConfig` - Register a new unit.
+* `removeUnitConfig(unitId: String): UnitConfig` - Remove a unit by its id.
+* `updateUnitConfig(unitConfig: UnitConfig): UnitConfig` - Update a unit config. Note: the values of the provided unit config will be merged into the current one (retrieved through the provided id). This means that all values which are lists will just be appended to the current list.
+* `updateMetaConfig(unitId: String, entry: Entry): MetaConfig` - Update an entry in the toplevel meta config of a unit config.
+
+## Supported Headers
+The GraphQL API Server will process the following HTTP headers on requests:
+
+* **Authorization Header**:
+The `authorization` header can be used to authenticate your client at BCO.
+Just send the token received through a [login query](#supported-queries) as the value of the authorization header with your requests. 
+If this header is not supplied, your actions will be performed with other permissions.
+
+* **Accept-Language Header**:
+If you set the `accept-language` header to a language code, the GraphQL API will resolve all multi language strings (eg. labels and descriptions) according to this language.
+On queries the text matching the language code are returned and on mutations the values matching your language code are modified.
+It this header is not set, the default of the server running the GraphQL API is used.
+
+## How to generate the password hash on client side
+
+The `passwordHash` needs to be generated as follows:
+1. Encoding the plain text password as `UTF16`
+2. Compute a hash of the `UTF16` bytes by using the `SHA-256` hash generator algorithm
+3. Encode the result as `Base64` and pass it to the login method as `passwordHash`.
+
+Dart Example:
+   ```dart
+   final hashedPassword = base64.encode(
+      sha256.convert(
+         encodeUtf16(plainPassword)
+      ).bytes);
+   ```
+Java Example:
+   ```java
+   final String hashedPassword = Base64.getEncoder()
+      .encodeToString(
+         EncryptionHelper.hash("plainPassword")
+      );
+   ```
+## Used Tools
+
+1. [GraphQL](https://graphql.org/)
+   * API Framework
+2. [Rejoiner](https://rejoiner.io/)
+   * Protobuffer type integration
+4. [Bonjour Service](https://github.com/jmdns/jmdns)
+   * Advertising and discovery of the graphql service within the local network

doc/docs/developer/addon/bco-cloud.md

@@ -0,0 +1,24 @@
+# BCO Cloud
+
+![Cloud Architecture](/img/bco/cloud/BCOCloudArchitecture.svg)
+
+## Cloud Server
+
+:::note TODO
+Write documentation
+:::
+
+[Source Code](https://github.com/openbase/bco.cloud)
+
+## Cloud Connector
+
+:::note TODO
+Write documentation
+:::
+
+[Source Code](https://github.com/openbase/bco.app/tree/master/cloudconnector)
+
+## Access heroku cloud log
+1. Install [heroku CLI](https://devcenter.heroku.com/articles/heroku-cli)
+2. Login with CLI: ```heroku login```
+3. View logs: ```heroku logs -a bco-cloud``` or ```heroku logs -a bco-cloud --tail``` 

doc/docs/developer/addon/bco-eveson.md

@@ -0,0 +1,26 @@
+---
+---
+# BCO Eveson
+
+In smart environments, a myriad of sensors and processing components produce a very large amount of data every second. We implemented the framework Eveson which supports the monitoring through the generation of pleasant ambient soundscapes based on such complex data streams.
+
+![LocationGraphStructure](/img/bco/eveson/EvesonLogo.jpg)
+
+Eveson supports the individual selection of data streams and types and the configuration of how they should be sonified. The bundle of all data to sound mappings is stored in a theme configuration. For your prototype we especially selected only sounds of one natural environment (the German forest) to generate a familiar soundscape for the user.
+
+## Repository
+
+[Github: openbase/bco.eveson](https://github.com/openbase/bco.eveson)
+
+## How to Start the Application
+
+Since Eveson is a part of the default distribution of bco, you can simply start Eveson by executing:
+```
+bco-eveson
+```
+
+for more details checkout:
+
+```
+bco-eveson --help
+```

doc/docs/developer/addon/bco-ontology.md

@@ -0,0 +1,5 @@
+# BCO Ontology
+
+![Control Example On](/img/bco/bco-ontology.svg)
+
+[Source Code](https://github.com/openbase/bco.ontology)