Set Documentation style (mdlrc), Resolve Issues

.mdl_style.rb

@@ -1,4 +1,4 @@
 all
-rule 'MD013', :ignore_code_blocks => true
-rule 'MD013', :tables => false
-rule 'MD046', :indented => true
+exclude_rule 'MD033'
+rule 'MD013', :code_blocks => false, :tables => false
+rule 'MD046', :style => :fenced

client/README.md

@@ -1,10 +1,13 @@
 # Introduction
 
-Client (frontend) for Digital Twin as a Service (DTaaS) software. This software shall be used for providing a React single page web application for the Digital Twin support platform.
+Client (frontend) for Digital Twin as a Service (DTaaS) software.
+This software shall be used for providing a React single page web
+application for the Digital Twin support platform.
 
 ## Setup the Environment and Build
 
-The following steps are required to setup the environment and build the application.
+The following steps are required to setup the environment and build
+the application.
 
 ### Prerequisites
 
@@ -40,31 +43,44 @@ yarn test -e   #run end-to-end tests
 ## Authentication
 
 The react client website uses OAuth authentication.
-The [authentication page](../docs/admin/client/auth.md) provides details
-on setting up oauth authentication for the client application.
+The [authentication page](../docs/admin/client/auth.md)
+provides details on setting up oauth authentication for
+the client application.
 
 ## Custom configuration
 
-It is required to have a `env.js` in the root directory of `build` during runtime. This file is used to configure the endpoints of the application. See the [build instructions](../docs/admin/client/CLIENT.md) for an example.
+It is required to have a `env.js` in the root directory of
+`build` during runtime. This file is used to configure the
+endpoints of the application.
+See the [build instructions](../docs/admin/client/CLIENT.md)
+for an example.
 
 ### Multiple configurations
 
-If you want to switch between multiple environments, you can use the `yarn configapp` command to copy a configuration file from `client/config/` to the `build` directory.
+If you want to switch between multiple environments,
+you can use the `yarn configapp` command to copy a configuration
+file from `client/config/` to the `build` directory.
 
 1. Save the file as `client/config/<config-name>.js`.
-2. Run the config command to copy the file to the `public` directory and the `build` directory, if a build is present.
+1. Run the config command to copy the file to the `public` directory
+   and the `build` directory, if a build is present.
 
 ```bash
 yarn configapp <config-name>
 ```
 
-> Which ever env.js file is present in the `public` directory during `yarn build`, will be used in the build.
+> Which ever env.js file is present in the `public` directory during
+`yarn build`, will be used in the build.
 
-It is therefore reccommend to keep the configurations in the `client/config/` directory and use the `yarn configapp` command to switch between them.
+It is therefore reccommend to keep the configurations in the
+`client/config/` directory and use the `yarn configapp` command to
+switch between them.
 
 ## Example configuration for developers
 
-The first step is to collect the URL of gitlab acting as oauth provider. Also collect the client application id. With that information, a configuration file can be made.
+The first step is to collect the URL of gitlab acting as oauth provider.
+Also collect the client application id. With that information,
+a configuration file can be made.
 
 A suitable configuration file for developers is:
 
@@ -90,8 +106,9 @@ window.env = {
 
 Here the gitlab URL is `https://gitlab.foo.com/` and the client ID is `934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0`.
 
-If a basename is needed for the client application, then the configuration file needs to be updated with the basename. For example, with a basename of `au`,
-the `build/env.js` file is given below.
+If a basename is needed for the client application, then the configuration
+file needs to be updated with the basename. For example, with a basename of
+`au`, the `build/env.js` file is given below.
 
 ```js
 window.env = {
@@ -113,11 +130,15 @@ window.env = {
   REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api',
 ```
 
-Do remember that the oauth application on gitlab needs to have the redirect (callback) URL is correctly registered.
+Do remember that the oauth application on gitlab needs to have the redirect
+(callback) URL is correctly registered.
 
 ## Caveat
 
-The client website relies on the background services to provide most of the functionality. These services would not be running on the developer computer. The complete application setup exists either on the integration server or as an installation instance. During development, there will be 
+The client website relies on the background services to provide most of the
+functionality. These services would not be running on the developer computer.
+The complete application setup exists either on the integration server or as an
+installation instance. During development, there will be
 
 ```txt
 Unexpected Application Error!

client/test/README.md

@@ -1,33 +1,47 @@
 # End-to-End (E2E) Tests
 
-The E2E tests require a functional gitlab oauth setup, traefik gateway and a live react client website. The E2E tests do not launch the react client website. So it is important to launch the website using `yarn start`. Keep this server running while performing the E2E tests with `yarn test -e` command.
+The E2E tests require a functional gitlab oauth setup, traefik gateway and a
+live react client website. The E2E tests do not launch the react client website.
+So it is important to launch the website using `yarn start`. Keep this server
+running while performing the E2E tests with `yarn test -e` command.
 
-The E2E tests use playwright test runner. You also need to have the software installed. If it is not installed, you can install with the following command.
+The E2E tests use playwright test runner. You also need to have the software
+installed. If it is not installed, you can install with the following command.
 
 ```bash
 sudo npx playwright install-deps
 ```
 
 ## OAuth Setup
 
-You can follow the instructions in [authentication page](../../docs/admin/client/auth.md) to setup oauth for the react client website. Remember to add the `http://localhost:4000` as callback URL in the oauth application. The gitlab will still be running on a remote machine. It is not possible to run both the gitlab and react client website on localhost.
+You can follow the instructions in
+[authentication page](../../docs/admin/client/auth.md) to setup oauth for the
+react client website. Remember to add the `http://localhost:4000` as callback URL
+in the oauth application. The gitlab will still be running on a remote machine.
+It is not possible to run both the gitlab and react client website on localhost.
 
 ## config/test.js file
 
-Before running the E2E tests, you need to update the `config/test.js` file. If you have a live DTaaS client website running, you can copy the `build/env.js` into `config/test.js`.
+Before running the E2E tests, you need to update the `config/test.js` file.
+If you have a live DTaaS client website running, you can copy the `build/env.js`
+into `config/test.js`.
 
-Open `config/test.js` in a text editor and make sure the configuration matches the details of your testing environment. For instance, you need to adjust:
+Open `config/test.js` in a text editor and make sure the configuration matches
+the details of your testing environment. For instance, you need to adjust:
 
 * `REACT_APP_URL`
 * `REACT_APP_AUTH_AUTHORITY`
 * `REACT_APP_REDIRECT_URI`
 * `REACT_APP_LOGOUT_REDIRECT_URI`
 
-to reflect your test setup. More information on about the environment settings is available in [authentication](../../docs/admin/client/auth.md) and [client deployment](../../docs/admin/client/CLIENT.md) pages.
+to reflect your test setup. More information on about the environment settings is
+available in [authentication](../../docs/admin/client/auth.md) and
+[client deployment](../../docs/admin/client/CLIENT.md) pages.
 
-Here's an example of relevant values for variables. This example is suitable for testing on developer computer.
+Here's an example of relevant values for variables. This example is suitable for
+testing on developer computer.
 
-```
+```js
 REACT_APP_URL="http://localhost:4000"
 REACT_APP_AUTH_AUTHORITY="http://gitlab.foo.com"
 REACT_APP_REDIRECT_URI="http://localhost:4000/Library"
@@ -36,7 +50,9 @@ REACT_APP_LOGOUT_REDIRECT_URI="http://localhost:4000"
 
 ## env file
 
-You need to create a `test/.env` file where you will store the GitLab user credentials. These credentials will be used by playwright to simulate real user interactions during the E2E tests.
+You need to create a `test/.env` file where you will store the GitLab user
+credentials. These credentials will be used by playwright to simulate real
+user interactions during the E2E tests.
 
 A template for `test/.env` is given here:
 
@@ -46,11 +62,14 @@ REACT_APP_TEST_PASSWORD=your_password
 REACT_APP_URL='https://foo.com'
 ```
 
-Replace _your_username_ and _your_password_ with the actual username and password of your GitLab account or the testing account that you intend to use. Finally replace _foo.com_ with the URL of your application, as you did in `env.js`.
+Replace _your_username_ and _your_password_ with the actual username and password
+of your GitLab account or the testing account that you intend to use. Finally
+replace _foo.com_ with the URL of your application, as you did in `env.js`.
 
-Here's an example for test setup on the developer machine and on the integration server:
+Here's an example for test setup on the developer machine and on the
+integration server:
 
-```
+```env
 REACT_APP_TEST_USERNAME=TestUsername
 REACT_APP_TEST_PASSWORD=TestPassword123
 REACT_APP_URL='http://localhost:4000'
@@ -63,12 +82,16 @@ There are two possible testing setups you can create.
 1. Host website on the developer computer and test from developer computer
 1. Host website on the integration server and test from the integration server
 
-If you use `localhost` in the `REACT_APP_URL` the above the two mentioned setups are essentially the same. 
-In order to run the tests on the integration server, you need to disable the HTTP authentication (if setup in the first place) on the Traefik server and let the website be accessible without any authenticaiton.
+If you use `localhost` in the `REACT_APP_URL` the above the two mentioned setups
+are essentially the same.
+In order to run the tests on the integration server, you need to disable the
+HTTP authentication (if setup in the first place) on the Traefik server and
+let the website be accessible without any authenticaiton.
 
 ### The configuration files for the test on localhost
 
-The `config/test.js` file is given below. The `build/env.js` also holds the same content.
+The `config/test.js` file is given below. The `build/env.js` also holds the
+same content.
 
 ```js
 window.env = {
@@ -91,21 +114,26 @@ window.env = {
 };
 ```
 
-**test/.env**
+## test/.env - localhost
 
 ```ini
 REACT_APP_TEST_USERNAME=TestUsername
 REACT_APP_TEST_PASSWORD=TestPassword123
 REACT_APP_URL='http://localhost:4000'
 ```
 
-Please note that the username and password are the user credentials on `gitlab.foo.com`.
+Please note that the username and password are the user
+credentials on `gitlab.foo.com`.
 
 ## Testing on the integration server
 
-In this test setup, the DTaaS application is running at `https://foo.com` and the gitlab instance is running at `https://gitlab.foo.com`. The E2E test shall be run from the developer computer. The codebase commit should be the same on both the developer computer and integration server.
+In this test setup, the DTaaS application is running at `https://foo.com` and
+the gitlab instance is running at `https://gitlab.foo.com`. The E2E test shall
+be run from the developer computer. The codebase commit should be the same on
+both the developer computer and integration server.
 
-The `config/test.js` file on the developer computer is given below. The `build/env.js` of the integration server also holds the same content.
+The `config/test.js` file on the developer computer is given below. The
+`build/env.js` of the integration server also holds the same content.
 
 ```js
 window.env = {
@@ -128,7 +156,7 @@ window.env = {
 };
 ```
 
-**test/.env**
+## test/.env - Integration server
 
 ```ini
 REACT_APP_TEST_USERNAME=TestUsername
@@ -138,13 +166,20 @@ REACT_APP_URL='https://foo.com'
 
 Please note that the username and password are the user credentials on `gitlab.foo.com`.
 
-**NOTE:** The tests from developer computer to the integration server only work with null basename. The test fails if a basename (say `au`) is specified. This might be due to a complex interaction of developer computer, traefik gateway and the client website hosted behind traefik.
+**NOTE:** The tests from developer computer to the integration server only
+work with null basename. The test fails if a basename (say `au`) is specified.
+This might be due to a complex interaction of developer computer, traefik
+gateway and the client website hosted behind traefik.
 
 ## Running the Tests
+
 Once you've properly set up your .env file, you can now run the end-to-end tests.
 
-```
+```bash
 yarn test -e
 ```
-This command launches the test runner and executes all end-to-end tests. Make sure you have an active internet connection while running these tests, as they simulate real user interactions with your GitLab account.
+
+This command launches the test runner and executes all end-to-end tests.
+Make sure you have an active internet connection while running these tests,
+as they simulate real user interactions with your GitLab account.
 

deploy/README.md

@@ -114,4 +114,4 @@ You can run this script multiple times until the installation is successful.
 
 ## Access the application
 
-Now you should be able to access the DTaaS application at: _https://foo.com_
+Now you should be able to access the DTaaS application at: _<http:>https://foo.com</http:>_

deploy/vagrant/make_boxes/dtaas/README.md

@@ -1,15 +1,18 @@
+# DTaaS Boxes
+
 This is a box that has the following items:
+
 * docker
 * nodejs and yarn
 * jupyter
 * microk8s
 * containers
-    * mltooling/ml-workspace:0.13.2
-    * traefik2.5
-    * influxdb2.4
-    * grafana
-    * telegraf
-    * gitlab
+  * mltooling/ml-workspace:0.13.2
+  * traefik2.5
+  * influxdb2.4
+  * grafana
+  * telegraf
+  * gitlab
 
 Publish a base virtualbox package to be used by
 vagrant to publish all other virtualbox packages
@@ -28,21 +31,21 @@ vagrant ssh
 
 # install the oh-my-zsh
 sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
-# install plugins: history, autosuggestions, 
+# install plugins: history, autosuggestions,
 git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
 
 # inside ~/.zshrc, modify the following line
 plugins=(git zsh-autosuggestions history cp tmux)
 
-# remove the vagrant default public key - first line of 
+# remove the vagrant default public key - first line of
 # /home/vagrant/.ssh/authorized_keys
 
 # exit vagrant guest machine and then
 # copy own private key to vagrant private key location
 cp vagrant .vagrant/machines/default/virtualbox/private_key
 
 # check
-vagrant ssh	#should work
+vagrant ssh #should work
 
 vagrant halt
 
@@ -57,5 +60,6 @@ vagrant box add --name dtaas ./dtaas.vagrant
 ```
 
 ## TODO
+
 1. Write a script for automating the above steps
 1. Generate the ssh keys from ssl/certificates.bash

deploy/vagrant/single-machine/README.md

@@ -4,21 +4,25 @@ This directory contains code for running DTaaS application inside one
 vagrant VM. The setup requires a machine which can spare 16GB RAM,
 8 vCPUs and 50GB Hard Disk space to the vagrant box.
 
-A dummy **foo.com** URL has been used for illustration. Please change this to your unique website URL.
+A dummy **foo.com** URL has been used for illustration.
+Please change this to your unique website URL.
 
 Please follow these steps to make this work in your local environment.
 
 1. Create [**dtaas** Vagrant box](../make_boxes/dtaas/README.md).
    You would have created an SSH key pair - _vagrant_ and
    _vagrant.pub_ for the vagrant box.
    The _vagrant_ is the private SSH key and is needed for the next steps.
-   Copy _vagrant_ SSH private key into the current directory (`deploy/vagrant/single-machine`).
+   Copy _vagrant_ SSH private key into the current
+   directory (`deploy/vagrant/single-machine`).
    This shall be useful for logging into the vagrant machine
    created for single-machine deployment.
 
 1. Update the **Vagrantfile**. Fields to update are:
     1. Hostname (`node.vm.hostname = "foo.com"`)
-    1. MAC address (`:mac => "xxxxxxxx"`). This change is required if you have a DHCP server assigning domain names based on MAC address. Otherwise, you can leave this field unchanged.
+    1. MAC address (`:mac => "xxxxxxxx"`). This change is required
+       if you have a DHCP server assigning domain names based on MAC
+       address. Otherwise, you can leave this field unchanged.
     1. Other adjustments are optional.
 1. Execute the following commands from terminal