Virtual Robot - Java Documentation (#41)

_includes/thumbnail.html

@@ -1,6 +1,6 @@
 <div class="row pb-4 pt-1">
     <div class="col-sm-12 col-md-11 col-lg-10 mx-auto">
-        <img class="px-5 py-2 img-fluid img-thumbnail mx-auto d-block mw-100 {{ include.class }}"
+        <img class="px-2 py-2 img-fluid img-thumbnail mx-auto d-block mw-100 {{ include.class }}"
             src="{{ include.src }}" alt="{{include.alt}}">
     </div>
 </div>

assets/css/index.css

@@ -433,4 +433,16 @@ table {
     color: #141619;
     background-color: #d3d3d4;
     border-color: #bcbebf;
+}
+
+.alert p {
+    margin-bottom: 0 !important;
+}
+
+.language-plaintext {
+    border: none !important;
+    background-color: #ebebeb;
+    margin: 0;
+    padding: 2px 6px !important;
+    border-radius: 4px;
 }

docs/robots/virtual/v1/java/0_intro.md

@@ -0,0 +1,17 @@
+---
+layout: default
+title: Java Robot
+parent: Virtual Robots
+has_children: true
+permalink: robots/virtual/v1/java/
+
+---
+
+# Virtual Robot - Java Implementation
+
+[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0) [![Java CI with Maven](https://github.com/Pera-Swarm/java-robot/actions/workflows/java-ci.yml/badge.svg)](https://github.com/Pera-Swarm/java-robot/actions/workflows/java-ci.yml)
+
+---
+
+
+Autogenerated Documentation can be found on [https://pera-swarm.ce.pdn.ac.lk/robot-library-java/](https://pera-swarm.ce.pdn.ac.lk/robot-library-java/)

docs/robots/virtual/v1/java/1_setup-guide.md

@@ -0,0 +1,89 @@
+---
+layout: default
+parent: Java Robot
+grand_parent: Virtual Robots
+title: Java Robot
+nav_order: 1
+permalink: robots/virtual/v1/java/setup-guide/
+
+gh_link: docs/robots/virtual/v1/java/1_setup-guide.md
+---
+
+# Setup Guide for the Java Robot
+{: .no_toc }
+
+This will guide you to set up the Java Robot implementation of the Pera-Swarm virtual robots, by importing necessary dependencies, doing the configurations, and implementing your own first virtual robot instance.
+
+##### Table of content
+{: .no_toc }
+- TOC
+{:toc}
+
+----
+
+## Getting started
+
+If you are interested in only the robot functionalities and applications, not the core functionalities, you can start with the *pre-build* Java Library of the Virtual Robot library, and write your Virtual Robots.
+
+
+## Environment Setup
+
+- You need to fork and/or clone the repository, [Pera-Swarm/java-robot](https://github.com/Pera-Swarm/java-robot){:target="_blank"}.
+
+- Create a file named `mqtt.properties` in the path, `./src/resources/config/` as follows, and provide your MQTT broker's configurations. You can select any channel, as same as your simulation server runs on.
+
+```xml
+server=127.0.0.1
+port=1883
+username=user
+password=pass
+channel="v1"
+```
+
+- Next, need to obtain a GitHub _Personal Access Token_ with the scope of `read:packages`, by following [this](https://github.com/settings/tokens/new) URL. Create it with a preferable expiration time and a Note. You need to copy this and save it somewhere to be used in the next step.
+
+{% include thumbnail.html src="/docs/assets/images/java-robot/github-token.png" alt="GitHub token" %}
+
+- As the next step, create a file named `settings.xml` in the root directory of the repository, by copying `settings.sample.xml`.
+
+- Update **{GITHUB_USERNAME}** with your GitHub username and **{GITHUB_TOKEN}** with the Personal Access Token you obtained in the previous step. 
+
+```xml 
+<server>
+    <id>github</id>
+    <username>{GITHUB_USERNAME}</username>
+    <password>{GITHUB_TOKEN}</password>
+</server>
+```
+
+{% include alert.html message="Please note that this **settings.xml** file should not be committed into the git history, since it contains a secret value." type="alert-danger" %}
+
+- Next, run the following command to run the `mvn install`. It will download the necessary dependencies from _Maven Central Repository_ and _GitHub Package Repository_.
+
+```bash 
+mvn -s ./settings.xml -B install --file pom.xml 
+```
+
+### Run using IDE 
+
+- You can open the `src/main/java/swarm/App.java` file and run it using the **Run** or **Debug** option in the IDE to initiate the running of the implementation.
+
+- If you are using VSCode IDE, you can select the **Run and Debug** tool, and start using 'Run a Swarm'.
+
+### Run using Command Line 
+
+- Compile the packages and assembly with all the dependencies, using `mvn compile assembly:single`
+
+```bash 
+mvn clean compile assembly:single -s settings.xml 
+```
+
+- Run the code implementation using `java -jar [jar_file_path]`
+
+```bash 
+java -jar target/java-robot-node-1.0-SNAPSHOT-jar-with-dependencies.jar 
+```
+
+## Additional Readings
+
+- [Maven - Environment Setup](https://www.tutorialspoint.com/maven/maven_environment_setup.htm){:target="_blank"}

docs/robots/virtual/v1/java/2_setup-guide-library.md

@@ -0,0 +1,88 @@
+---
+layout: default
+parent: Java Robot
+grand_parent: Virtual Robots
+title: Java Robot Library
+nav_order: 2
+permalink: robots/virtual/v1/java/setup-guide-library/
+
+gh_link: docs/robots/virtual/v1/java/2_setup-guide-library.md
+---
+
+# Setup Guide for the Java Robot Library
+{: .no_toc }
+
+The **Java Robot Library** is the core of the Java Robots, which is implemented on Java, based on OOP concepts, and build using the Maven build system. It will be also available through Maven Package Repository maintained by GitHub from [here](https://github.com/Pera-Swarm/robot-library-java/packages).
+
+This will guide you to setup the core library of the Pera-Swarm virtual robots, by importing the necessary dependencies, and doing the configurations.
+
+##### Table of content
+{: .no_toc }
+- TOC
+{:toc}
+
+----
+
+## Getting started
+
+If you need to update the core functionalities, while the robot implementations, you need to  fork and clone the repository, [Pera-Swarm/robot-library-java](https://github.com/Pera-Swarm/robot-library-java){:target="_blank"} first. Then you need to install the dependencies and compile the project with your changes, and later work on a release.
+
+It is recommended to use an IDE like **Visual Studio Code** / **IntelliJ IDEA**, since it will help you to install dependencies easily.
+
+- Download the repository from [Pera-Swarm/robot-library-java](https://github.com/Pera-Swarm/robot-library-java){:target="_blank"}
+
+- Once you download the repository, you need to copy the `src/resources/config/sample_mqtt.properties` file and create `src/resources/config/sample_mqtt.properties`.
+
+- You need to update the following values with the values of the **MQTT Broker** you are using.
+
+```bash
+server=127.0.0.1
+port=1883
+username=user
+password=pass
+channel=v1
+```
+
+- Install Packages and Dependencies using **mvn install** command
+- Compile using **mvn compile** command
+- You can open the `src/main/java/swarm/App.java` file and run it using the **Run** or **Debug** option in the IDE to initiate the running of the implementation.
+
+
+Auto-generated full documentation of the available _Class_ and _Methods_ can be found at [http://pera-swarm.ce.pdn.ac.lk/robot-library-java/](http://pera-swarm.ce.pdn.ac.lk/robot-library-java/).
+
+{% include alert.html message="It is assumed that you already installed _Java Runtime Environment_ and _Maven Build Tool_." type="alert-primary" type="alert-warning" %}
+
+## Publishing a new version 
+
+- You need to update the version of the package in the **./pom.xml** file, with the version you hope to release. 
+
+```xml 
+<groupId>pera.swarm</groupId>
+<artifactId>java-robot</artifactId>
+<version>1.0.0</version>
+```
+
+- Next, you can prepare the release via GitHub from [here](https://github.com/Pera-Swarm/robot-library-java/releases). The release process will be done automatically via [Maven Publish](https://github.com/Pera-Swarm/robot-library-java/blob/main/.github/workflows/maven-publish.yml) GitHub CI Action workflow at a release.
+
+- Next, you can use the following code block to use the Java Library on your Maven Projects. Replace the &lt;version&gt;1.0.0&lt;/version&gt; with the version you want to use. (Please note that to use this Maven library, you need to Authenticate with a GitHub token. Further info is available [here]({{ '/robots/virtual/v1/java/setup-guide/' | relative_url }}).) 
+
+```xml 
+<dependency>
+  <groupId>pera.swarm</groupId>
+  <artifactId>java-robot</artifactId>
+  <version>1.0.0</version>
+</dependency>
+```
+
+
+## Additional Readings
+
+### What is Maven ?
+
+Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information. Using maven we can build and manage any Java based project.
+
+### Why Maven was used ?
+
+Since this repository is based on OOP concepts and have a few dependencies on ready made libraries, it was required to have a proper project management and dependency management tool. It will help to build the project easily.  
+
+- [Maven - Environment Setup](https://www.tutorialspoint.com/maven/maven_environment_setup.htm){:target="_blank"}