docs: Added Markdown files for Documentation (#378)

* [add]: docs/Quickstart guide to get the user started * [add]: Getting-Started.md to help users install drifty on various OS * [add]: Drifty Demo video * [add]: Dirfty Explanations * [add]: FAQ Docs for better troubleshooting of the project for the end users * [fix]: Linter errors in Quickstart.md * [fix]: linters on line 17 of quickstart.md * [add]: Project(s) Contribution Guide * update: Contribution as well as the quickstart guide to go for review * Update: Website/app/docs/Quickstart.md Changed parallel to multhreaded Co-authored-by: Saptarshi Sarkar <saptarshi.programmer@gmail.com> * Fixed Typo Co-authored-by: Saptarshi Sarkar <saptarshi.programmer@gmail.com> * Fixed Typos by Saptershi Co-authored-by: Saptarshi Sarkar <saptarshi.programmer@gmail.com> * docs: Updated Installation Video in Quickstart * Update Website/app/docs/Contribution.md Co-authored-by: Saptarshi Sarkar <saptarshi.programmer@gmail.com> * Update Website/app/docs/Contribution.md Co-authored-by: Saptarshi Sarkar <saptarshi.programmer@gmail.com> * Update Website/app/docs/Contribution.md Co-authored-by: Saptarshi Sarkar <saptarshi.programmer@gmail.com> * docs: Refactored some lines in the FAQ and Contributing files * docs: Rewritten Quickstart, Getting Started and Contributing, and also added images for detailed instructions to download and install Drifty * fix(CI): Fixed linter issues * fix(CI): Fixed linter issues * feat(docs): Organized development flow and added more details in the instructions for setting up the project * fix(CI): Fixed linter issue * feat(docs): Added steps to generate graalvm metadata for both Drifty CLI and GUI before building executables * fix(CI): Fixed all typos and sentence improvements provided by CodeRabbitAI bot * docs: Added Usage guidelines for both Drifty CLI and Drifty GUI An overview of both the Drifty CLI commands and a detailed description of the UI components of the Drifty GUI has been added. Steps to download a file using both Drifty CLI and GUI have also been added * docs: Added images for Usage guidelines of Drifty CLI * docs: Fixed Coderabbit AI reviews * docs: Fixed a grammatical error provided by Coderabbit AI Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --------- Co-authored-by: Saptarshi Sarkar <saptarshi.programmer@gmail.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
SaptarshiSarkar12 · Aug 12, 2024 · 2ba8b07 · 2ba8b07
1 parent 63059df
commit 2ba8b07
Show file tree

Hide file tree

Showing 14 changed files with 867 additions and 2 deletions.
diff --git a/.github/linters/.markdown-lint.yml b/.github/linters/.markdown-lint.yml
@@ -7,7 +7,8 @@ MD004:
 MD005: true # Inconsistent indentation for list items at the same level
 MD022: true # Headers should be surrounded by blank lines
 MD023: true # Headers must start at the beginning of the line
-MD024: true # Multiple headers with the same content
+MD024:
+  siblings_only: true # Multiple headers with the same content under different nesting levels are allowed
 MD026:
   punctuation: ".,;:!" # Trailing punctuation in header
 MD027: true # Multiple spaces after blockquote symbol

diff --git a/.idea/misc.xml b/.idea/misc.xml
diff --git a/Website/app/docs/Contributing.md b/Website/app/docs/Contributing.md
@@ -0,0 +1,72 @@
+# Contributing to Drifty
+
+Drifty is an Open-Source project, and we encourage contributions from the community.
+Thank you for considering and taking the time to contribute!
+The following are the guidelines for contributing to this project.
+
+## Code of Conduct
+
+We have a [Code of Conduct](https://github.com/SaptarshiSarkar12/Drifty/blob/master/CODE_OF_CONDUCT.md) that all contributors must follow.
+This code of conduct outlines our expectations for participants within the project. It also includes steps to report unacceptable behavior.
+We are committed to providing a welcoming and inspiring community for all and expect our code of conduct to be honored. Anyone who violates or has concerns about the code of conduct should report it directly to the project maintainers.
+
+## How to Report Bugs and Issues
+
+To report any bugs or any difficulties you are facing, you can create an issue by following the below steps 👇
+
+1. Go to the [issues](https://github.com/SaptarshiSarkar12/Drifty/issues) tab of the drifty project on GitHub
+2. Click on the [new issue](https://github.com/SaptarshiSarkar12/Drifty/issues/new/choose) button
+3. Choose the relevant category of the issue which you would like to raise
+4. Provide as much information as possible, including screenshots, text output, and both your expected and actual results.
+
+## What does each Issue Category mean?
+
+1. **Bug Report for Application**:
+   You can create a **Bug Report for Application** to report any bug related to the application, including installation problems and crashes.
+2. **Bug report for Website**:
+    You can create an issue in this category if you encounter any bugs or issues in the [official website of Drifty](https://saptarshisarkar12.github.io/Drifty/).
+3. **Documentation Change Request**:
+    Raise an issue if you think any improvements can be made in the Documentation of Drifty.
+4. **Feature Request for Drifty Application**:
+    If you have any ideas to improve the application by adding new features, you can create an issue in this category.
+5. **Feature Request for Drifty Website**:
+    If you have any ideas to improve the Website of Drifty by adding new features, you can create an issue in this category.
+
+If none of the above categories applies to your case, feel free to create an issue in the **Others** category.
+
+## Pull Requests
+
+[Pull requests](https://github.com/SaptarshiSarkar12/Drifty/pulls) are a fantastic way to bring your ideas to life in this project! Start by opening an issue to describe your proposed changes and discuss them with the maintainers. Once the issue is assigned to you, you can go ahead and submit your pull request.
+
+## What does each Label mean in Issues and Pull Requests?
+
+1. **App 💻**
+    This label indicates that changes are made in the Application code
+2. **bug 🐛**
+    This label indicates that changes are made to fix a bug
+3. **dependencies 📦️**
+    This label indicates that dependencies are updated in a Pull Request
+4. **docker 🐋**
+    This label indicates that changes are made in the Dockerfiles
+5. **documentation 📝**
+    This label indicates that changes are made in the documentation
+6. **good first issue**
+    This label indicates that the issue is suitable for beginners to start contributing
+7. **help wanted**
+    This label indicates that the issue requires help from the community
+8. **invalid**
+   This label is used to mark an issue or Pull Request as invalid, meaning it does not meet the project's guidelines or is not relevant to the project's goals.
+9. **CI/CD 🔁**
+    This label indicates that changes are made in the CI/CD workflows (GitHub Actions)
+10. **duplicate**
+     This label indicates that the issue / Pull Request is duplicate
+11. **hacktoberfest**
+     This label indicates that the issue is a part of [Hacktoberfest](https://hacktoberfest.com/)
+12. **hacktoberfest-accepted**
+     This label indicates that the Pull Request is accepted for [Hacktoberfest](https://hacktoberfest.com/) and will count towards your participation
+
+## Project Insights: Status and Task Progress
+
+[Projects Tab](https://github.com/users/SaptarshiSarkar12/projects/3) lists the tasks completed, in progress and the ideas left to be incorporated in the project. You can work on the **to-do tasks** by creating the issue (if not already created) and getting yourself assigned.
+
+![Project Insights](https://github.com/user-attachments/assets/292c5c90-fbee-4eb0-8912-02faea96ad23)
diff --git a/Website/app/docs/Development/Architecture.md b/Website/app/docs/Development/Architecture.md
@@ -0,0 +1,33 @@
+# Architecture
+
+## Project Structure
+
+The project is organized into the following directories:
+
+- `.github`: Contains the GitHub Actions workflows, issue and pull request templates, linter configuration files, and other GitHub-specific files.
+- `CLI`: Maven child module containing the source code for the Drifty CLI.
+- `GUI`: Maven child module containing the source code for the Drifty GUI.
+- `Core`: Maven child module containing the shared code between the CLI and GUI.
+- `Website`: Contains the source code for the Drifty website (A Next.js application).
+- `config`: Contains the configuration files for building the native installers and executables.
+- `Docker`: Contains the Dockerfile to build and run the Drifty application in a Docker container.
+  - `dev`: Contains the Dockerfiles to build and run the Drifty application in a Docker container for development purposes.
+    - `CLI`: Contains the Dockerfile to build and run the Drifty CLI executable in a Docker container for development purposes.
+    - `GUI`: Contains the Dockerfile to build and run the Drifty GUI executable in a Docker container for development purposes.
+    - `commons`: Contains the Dockerfiles for the base images used by the Drifty CLI and GUI Dockerfiles.
+  - `prod`: Contains the Dockerfile to build and run the Drifty application in a Docker container for production purposes.
+    - `CLI`: Contains the Dockerfile to build the Docker image for the Drifty CLI executable.
+    - `GUI`: Contains the Dockerfile to build the Docker image for the Drifty GUI executable.
+
+## Technologies Used
+
+The Drifty project uses the following technologies:
+
+- [**Java**](https://www.java.com/): The project is written in Java, which is a high-level, class-based, object-oriented programming language.
+- [**JavaFX**](https://openjfx.io/): The project uses JavaFX as the GUI toolkit for Drifty GUI.
+- [**Maven**](https://maven.apache.org/): The project uses Maven as the build automation and project management tool.
+- [**GraalVM**](https://www.graalvm.org/): The project uses GraalVM to build native executables for the Drifty CLI and GUI.
+- [**GluonFX Maven Plugin**](https://github.com/gluonhq/gluonfx-maven-plugin): The project uses the GluonFX Maven Plugin (which uses GraalVM under the hood) to build native executables for the Drifty GUI.
+- [**Next.js**](https://nextjs.org/): The project uses Next.js to build the Drifty website.
+- [**Docker**](https://www.docker.com/): The project uses Docker to containerize the Drifty application for development and production purposes.
+- [**GitHub Actions**](https://docs.github.com/en/actions): The project uses GitHub Actions for CI/CD workflows.
diff --git a/Website/app/docs/Development/Building-Executables.md b/Website/app/docs/Development/Building-Executables.md
@@ -0,0 +1,163 @@
+# Building Installer or Executable Binaries for Drifty
+
+## Generating GraalVM Metadata
+
+> [!NOTE]
+> This step is required only if you want to see your changes reflected in Drifty CLI or GUI executables.
+> If you are only interested in building the installer or executable binaries, you can skip this step.
+
+### Prerequisites
+
+- [Java 21](https://www.oracle.com/java/technologies/downloads/#java21)
+- [Download](https://maven.apache.org/download.cgi#previous-stable-3-8-x-release) and [install](https://maven.apache.org/install.html) **Maven** (Maven v3.8.8 is required for generating GraalVM metadata for Drifty GUI)
+- [GraalVM 21](https://www.graalvm.org/downloads/)
+
+### Steps
+
+1. Open the terminal and navigate to the project directory
+2. Follow the below instructions to generate GraalVM metadata for Drifty CLI or GUI
+   - For Drifty GUI,
+     - Navigate to the `GUI` directory
+       ```shell
+       cd GUI
+       ```
+     - Run the below command to generate GraalVM metadata for Drifty GUI
+       ```shell
+       mvn gluonfx:runagent
+       ```
+   - For Drifty CLI,
+     - Navigate to the `CLI` directory
+       ```shell
+       cd CLI
+       ```
+     - Run the below command to generate GraalVM metadata for Drifty CLI
+       ```shell
+       mvn -P generate-graalvm-metadata exec:exec@java-agent
+       ```
+3. Upon completion of the command, the GraalVM metadata will be generated in `src/main/resources/META-INF/native-image` directory of the respective project (`GUI` or `CLI`) directory.
+
+## Local Build
+
+### Prerequisites
+
+- [Java 21](https://www.oracle.com/java/technologies/downloads/#java21)
+- [Download](https://maven.apache.org/download.cgi#previous-stable-3-8-x-release) and [install](https://maven.apache.org/install.html) **Maven** (Maven v3.8.8 is required for building installer or executable binaries for Drifty GUI, locally)
+- [GraalVM 21](https://www.graalvm.org/downloads/)
+- [GCC](https://gcc.gnu.org/install/)
+
+### Steps
+
+> [!NOTE]
+> Check if GraalVM is added to the system path by running `native-image --version` in the terminal.
+> If the command is not recognized, add the GraalVM `bin` directory to the system path.
+> ```shell
+> PATH=$GRAALVM_HOME/bin
+> ```
+> Set the following environment variable to point to your GraalVM installation directory.
+> ```shell
+> GRAALVM_HOME=<path-to-graalvm>
+> ```
+> Replace `<path-to-graalvm>` with the actual path to the GraalVM installation directory.
+
+1. Open the terminal and navigate to the project directory
+2. Assuming you have installed the necessary project dependencies, run the below command to generate the C object file required only for building executable binaries for Drifty GUI
+   - For Linux,
+     ```shell
+     gcc -c config/missing_symbols.c -o config/missing_symbols-ubuntu-latest.o
+     ```
+   - For Windows,
+     ```shell
+     gcc -c config/missing_symbols.c -o config/missing_symbols-windows-latest.o
+     ```
+   - For macOS,
+     ```shell
+     gcc -c config/missing_symbols.c -o config/missing_symbols-macos-latest.o
+     ```
+   Replace `gcc` with the path to the GCC compiler if it is not in the system path.
+3. Run the below command to build the installer or executable binaries
+   - For Drifty GUI,
+     - For Linux,
+       ```shell
+       mvn -P build-drifty-gui-for-ubuntu-latest gluonfx:build gluonfx:package -rf :GUI -U
+       ```
+     - For Windows,
+       ```shell
+       mvn -P build-drifty-gui-for-windows-latest gluonfx:build gluonfx:package -rf :GUI -U
+       ```
+     - For macOS,
+       ```shell
+       mvn -P build-drifty-gui-for-macos-latest gluonfx:build gluonfx:package -rf :GUI -U
+       ```
+   - For Drifty CLI,
+     - For Linux,
+       ```shell
+       mvn -P build-drifty-cli-for-ubuntu-latest package
+       ```
+     - For Windows,
+       ```shell
+       mvn -P build-drifty-cli-for-windows-latest package
+       ```
+     - For macOS,
+       ```shell
+       mvn -P build-drifty-cli-for-macos-latest package
+       ```
+4. Upon completion of the build, the installer or executable binaries will be neatly organized in the directories listed below. The placeholder `{arch}` should be replaced with either `x86_64` or `aarch64`, depending on your system's architecture.
+   - For Drifty GUI,
+     - For Linux,
+       ```shell
+       GUI/target/gluonfx/{arch}-linux
+       ```
+     - For Windows,
+       ```shell
+       GUI/target/gluonfx/{arch}-windows
+       ```
+     - For macOS,
+       ```shell
+       GUI/target/gluonfx/{arch}-mac
+       ```
+   - For Drifty CLI,
+     - For Linux,
+       ```shell
+       CLI/target/CLI/linux
+       ```
+     - For Windows,
+       ```shell
+       CLI/target/CLI/windows
+       ```
+     - For macOS,
+       ```shell
+       CLI/target/CLI/mac
+       ```
+5. You can now run the installer or executable binaries to use the application.
+6. To remove the generated files, run the below command
+   ```shell
+   mvn clean
+   ```
+
+## Docker Build
+
+### Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/)
+- [Docker Compose](https://docs.docker.com/compose/install/)
+
+### Steps
+
+1. Open the terminal and navigate to the project directory
+2. Follow the below instructions to build and start the Drifty application in a Docker container
+   - For Drifty GUI,
+     - For Linux and Windows users,
+       - Run the below command to add access to the X server (required for GUI applications running in Docker)
+         ```shell
+         xhost +local:docker
+         ```
+       - Run the below command to build and start the Drifty GUI native executable in a Docker container
+         ```shell
+         docker compose run gui
+         ```
+     - For macOS users, please follow [these instructions](macOS%20Docker%20Build%20Instructions.md)
+   - For Drifty CLI,
+     Run the below command to build and start the Drifty CLI native executable in a Docker container
+     ```shell
+     docker compose run cli
+     ```
diff --git a/Website/app/docs/Development/Quickstart.md b/Website/app/docs/Development/Quickstart.md
@@ -0,0 +1,79 @@
+# Quick Start
+
+This is a quick start guide to get developers up and running with the project for development purposes.
+
+## Clone the Project
+
+> [!NOTE]
+> You need to have Git installed on your machine to clone the project. If you don't have Git installed, you can download it from [here](https://git-scm.com/downloads).
+
+Clone the Drifty repository to your local machine using the following command:
+
+```bash
+git clone git@github.com:SaptarshiSarkar12/Drifty.git
+```
+After the project has been cloned successfully, the **`Drifty`** directory will be created. Navigate into that directory.
+
+## Drifty Application Development
+
+### Prerequisites
+
+- [Java 21](https://www.oracle.com/java/technologies/downloads/#java21)
+- [Maven](https://maven.apache.org/download.cgi)
+- [IntelliJ IDEA](https://www.jetbrains.com/idea/) (**Recommended**)
+
+### Install Dependencies
+
+Install the dependencies required for the project using the following command:
+
+```bash
+mvn clean install
+```
+This command will install all the dependencies required for the maven project.
+
+### Running the Project in IntelliJ IDEA
+
+1. Open the project in IntelliJ IDEA.
+2. Follow the below steps to run the project:
+   - Open the `Drifty_CLI` Java class in the `CLI/src/main/java/main` directory and click on the run button. This will start the Drifty CLI application.
+   - Open the `Drifty_GUI` Java class in the `GUI/src/main/java/main` directory and click on the run button. This will start the Drifty GUI application.
+3. Make changes to the code and see them reflected in the application. Re-run the project after each change to see the updated output.
+
+### Debugging Drifty Application
+
+To debug the project, you can set breakpoints in the code and run the project in debug mode (by clicking on the debug button in IntelliJ IDEA). This will allow you to step through the code and inspect variables to identify and resolve issues.
+
+## Drifty Website Development
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/en/download/)
+- [npm](https://www.npmjs.com/get-npm)
+- [WebStorm](https://www.jetbrains.com/webstorm/) (**Recommended**) (You can also use any other IDE of your choice)
+
+### Install Dependencies
+
+Navigate to the `Website` directory and install the dependencies required for the website using the following command:
+
+```bash
+npm ci
+```
+
+### Running the Website Locally (Development Mode)
+
+To run the website locally in development mode, use the following command:
+
+```bash
+npm run dev
+```
+
+This will start the development server, and you can access the website at `http://localhost:3000` in your browser.
+Make changes to the website code from your IDE and see them reflected in real-time in the browser.
+
+### Debugging Drifty Website
+
+To debug the website, you can use the browser's developer tools to inspect the elements, view console logs, and debug JavaScript code. You can also use the `console.log()` function to log messages to the console for debugging purposes.
+
+## Contributing
+
+If you would like to contribute to the project, please read the [Contributing Guidelines](../Contributing.md) for more information on how to get started.