Merge pull request #4 from Evolutionary-Algorithms-On-Click/release_2

Complete examples and add FAQs

Author: Ashrockzzz2003

.vitepress/config.mjs

@@ -107,48 +107,61 @@ export default defineConfig({
         },
         nav: [
             { text: "Home", link: "/" },
-            { text: "Get Started", link: "/get-started" },
+            { text: "Get Started", link: "/introduction" },
             {
                 text: "Examples",
                 items: [
-                    { text: "EA Run", link: "/ea-run" },
-                    { text: "GP Run", link: "/gp-run" },
-                    { text: "PSO Run", link: "/pso-run" },
-                    { text: "DE Run", link: "/de-run" },
-                    { text: "Optimize ML Run", link: "/ml-run" },
+                    { text: "EA Run", link: "/user-guide/ea-run" },
+                    { text: "GP Run", link: "/user-guide/gp-run" },
+                    { text: "PSO Run", link: "/user-guide/pso-run" },
+                    { text: "DE Run", link: "/user-guide/de-run" },
+                    { text: "Optimize ML Run", link: "/user-guide/ml-run" },
                 ],
             },
             { text: "Team", link: "/team" },
         ],
 
         sidebar: [
             {
-                text: "Getting Started",
+                text: "Get Started",
+                collapsed: false,
+                items: [{ text: "Introduction", link: "/introduction" }],
+            },
+            {
+                text: "Installation",
                 collapsed: false,
                 items: [
-                    { text: "Setup Environment", link: "/get-started" },
-                    { text: "Backend Setup", link: "/backend-setup" },
-                    { text: "Frontend Setup", link: "/frontend-setup" },
+                    { text: "Pre-requisites", link: "/install/env-setup" },
+                    { text: "Backend Setup", link: "/install/backend-setup" },
+                    { text: "Frontend Setup", link: "/install/frontend-setup" },
                 ],
             },
             {
                 text: "User Guide",
                 collapsed: false,
                 items: [
-                    { text: "Register and Login", link: "/auth" },
+                    { text: "Register and Login", link: "/user-guide/auth" },
                     {
                         text: "Examples",
                         collapsed: false,
                         items: [
-                            { text: "EA Run", link: "/ea-run" },
-                            { text: "GP Run", link: "/gp-run" },
-                            { text: "PSO Run", link: "/pso-run" },
-                            { text: "DE Run", link: "/de-run" },
-                            { text: "Optimize ML Run", link: "/ml-run" },
+                            { text: "EA Run", link: "/user-guide/ea-run" },
+                            { text: "GP Run", link: "/user-guide/gp-run" },
+                            { text: "PSO Run", link: "/user-guide/pso-run" },
+                            { text: "DE Run", link: "/user-guide/de-run" },
+                            {
+                                text: "Optimize ML Run",
+                                link: "/user-guide/ml-run",
+                            },
                         ],
                     },
                 ],
             },
+            {
+                text: "FAQs",
+                collapsed: false,
+                items: [{ text: "Common Problems", link: "/FAQ" }],
+            },
             {
                 text: "Team",
                 collapsed: false,

FAQ.md

@@ -0,0 +1,52 @@
+---
+title: Troubleshooting Common Issues
+description: Solutions for common problems encountered while using EvOC, such as browser cache errors and internet connectivity issues affecting microservices.
+---
+
+# Troubleshooting Common Issues
+
+Encountering problems? Here are solutions for some common issues you might face while using EvOC.
+
+## Issue 1: Error Immediately After Clicking "Get Started"
+
+### Symptom
+
+After accessing the EvOC web application and clicking the **`Get Started`** or **`Sign Up`** button on the homepage, you immediately see an error message, potentially similar to this:
+
+![Error message appearing shortly after clicking Get Started, possibly related to loading resources](https://i.imgur.com/XCiKGpB.png)
+
+### Cause
+
+This often happens due to stale data stored in your web browser's cache from a previous visit or version of EvOC.
+
+### Solution: Hard Refresh
+
+The quickest solution is usually to perform a "hard refresh" of the page, which forces the browser to discard its cache and download the latest files from the server.
+
+- **On most browsers (Windows/Linux):** Press `Ctrl` + `Shift` + `R`
+- **On most browsers (Mac):** Press `Cmd` + `Shift` + `R` or `Cmd` + `Option` + `R`
+
+Alternatively, you can try clearing your browser's cache specifically for the EvOC site through your browser's settings menu.
+
+## Issue 2: Errors in Terminal Regarding Microservices (Local Install)
+
+### Symptom
+
+If you are running EvOC via a **local installation** (using Docker, etc.), you might see error messages appear in the terminal window where you launched the EvOC services. These errors often mention failures to connect to or fetch required microservices. The application UI might fail to load certain parts or become unresponsive. An example might look like this:
+
+![Terminal output showing error messages related to fetching or connecting to microservices](https://i.imgur.com/1x4NVoa.png)
+
+### Cause
+
+This typically indicates that the different backend components (microservices) of your local EvOC installation cannot communicate properly, often due to network connectivity problems between your machine and the resources those services need (or sometimes between the services themselves if networking is misconfigured).
+
+### Solution: Check Network & Restart
+
+1.  **Verify Internet Connectivity:** Ensure the machine running EvOC has a stable and active internet connection. Try accessing other websites.
+2.  **Check Network Configuration:** If using complex local network setups or VPNs, ensure they are not blocking communication required by EvOC's services.
+3.  **Restart EvOC Services:** Stop the running EvOC services in your terminal (usually with `Ctrl` + `C`). Wait a few seconds, and then restart them using the standard launch command (e.g., `docker compose up -d`).
+4.  **Retry:** Access the EvOC application interface again after restarting the services.
+
+::: danger Persistent Issue?
+If the problem continues after checking connectivity and restarting, consult the **[Local Installation Guide](./install/env-setup)** for more detailed setup verification steps or check for any specific network requirements mentioned there.
+:::

auth.md

@@ -3,34 +3,47 @@ layout: home
 
 hero:
     name: "EvOC"
-    text: "User documentation"
-    tagline: "Documentation for the Evolutionary Algorithms On Click (EvOC) Project"
+    text: "Run & Visualize EAs with Just a Click"
+    tagline: A user-friendly framework (Evolve On Click) for designing, executing, and analyzing various evolutionary algorithms (EA, GP, PSO, ML Tuning) through an intuitive graphical interface. Perfect for learners, researchers, and educators – no coding required to get started!
     image:
         src: "/logo.png"
         alt: "EvOC Logo"
     actions:
         - theme: brand
           text: Get Started
-          link: /get-started
+          link: /introduction
         - theme: alt
-          text: Explore
-          link: "/ea-run"
+          text: See Features in Action
+          link: /user-guide/ea-run
 
 features:
-    - title: "Configure"
+    - title: "Intuitive Configuration"
       icon: ⚙️
-      details: "Configure EA parameters for GP, PSO, DE, and traditional EA algorithms with ease."
-      link: "/ea-run"
-    - title: "Visualize"
+      details: "Visually configure parameters for Genetic Algorithms (GA), Genetic Programming (GP), Particle Swarm Optimization (PSO), and EA for ML Tuning via a simple GUI."
+      link: /user-guide/ea-run
+
+    - title: "Powerful Visualizations"
       icon: 📈
-      details: "Visualize algorithm results through graphs and logs."
-      link: "/ea-run"
-    - title: "Generate Code"
+      details: "Instantly visualize algorithm progress with fitness plots, understand results with GP trees, or observe swarm behavior with PSO animations."
+      link: /user-guide/ea-run
+
+    - title: "Transparent Code Generation"
       icon: 💻
-      details: "Generate Python code (powered by DEAP) for your configured algorithms."
-      link: "/ea-run"
-    - title: "Run, Save, & Share"
+      details: "Generate the underlying Python code (using the DEAP library) based on your GUI setup for transparency, learning, or further customization."
+      link: /user-guide/ea-run
+
+    - title: "EA for ML Tuning"
+      icon: 🧠
+      details: "Optimize Machine Learning model features or hyperparameters using Evolutionary Algorithms. Easily connect your data via Google Drive links."
+      link: /user-guide/ml-run
+
+    - title: "AI-Powered Explanations"
+      icon: ✨
+      details: "Don't understand the generated code or a specific EA concept? Ask the integrated EvOC AI for a clear explanation!"
+      link: /user-guide/ea-run
+
+    - title: "Execute, Save & Collaborate"
       icon: 🚀
-      details: "Execute algorithms, save results, and share your findings effortlessly."
-      link: "/ea-run"
+      details: "Run experiments, track your execution history, download logs, and easily share your configurations and results with others."
+      link: /user-guide/ea-run
 ---

de-run.md

@@ -1,3 +1,8 @@
+---
+title: Backend Setup
+description: Deploy the EvOC backend services locally using Docker Compose. This guide provides step-by-step instructions for setting up the backend environment.
+---
+
 # Deploying EvOC Backend Locally
 
 This guide will help you deploy the backend services of the Evolutionary Algorithms On Click (EvOC) project locally using Docker Compose.
@@ -54,7 +59,7 @@ AUTH_GRPC_ADDRESS = host.docker.internal:5001
 Run all services using the Docker Compose `.yml` file. Execute this command inside the `operations` directory:
 
 ```sh
-docker-compose up -d
+docker compose up -d
 ```
 
 Alternatively, click the `Run All Services` button at the start of the `.yml` file (if your IDE supports it):

ea-run.md

@@ -1,3 +1,8 @@
+---
+title: Installation Setup
+description: Step-by-step guide to set up the environment for running EvOC locally, including Docker Desktop installation, GMail Mailer account setup, and optional VS Code installation.
+---
+
 # Setup Environment
 
 ## Docker Desktop
@@ -20,3 +25,5 @@
 2.  Install the **Docker extension** from Microsoft to manage services inside Docker using `.yml` files.
 
 ![VS Code Docker Extension](https://i.imgur.com/4wMJyh6.png)
+
+<!-- TODO: Docs about getting a free Gemini API key for AI Features. -->

gp-run.md

@@ -1,3 +1,8 @@
+---
+title: Frontend Setup
+description: Step-by-step guide to deploy the EvOC frontend locally using Next.js. This guide includes cloning the repository, installing dependencies, and running the application.
+---
+
 # Deploying EvOC Frontend Locally
 
 The frontend is a Next.js application that communicates with the backend services. It is responsible for rendering the user interface and handling user interactions.
@@ -28,6 +33,8 @@ Create a `.env` file and paste the following configuration:
 NEXT_PUBLIC_BACKEND_BASE_URL=http://localhost:5002
 NEXT_PUBLIC_AUTH_BASE_URL=http://localhost:5000
 NEXT_PUBLIC_MINIO_BASE_URL=http://localhost:9000
+NEXT_PUBLIC_AI=false # If you need access to AI features, set this to true
+GOOGLE_GENERATIVE_AI_API_KEY=<YOUR_API_KEY> # If you need access to Google Generative AI features, set this to your API key
 ```
 
 ![env-content](https://i.imgur.com/v4RN8cv.png)