[29/01/23] Project documentation - Setup/Introduction

documentation/README.md

@@ -1,5 +1,7 @@
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+```
 
+```
 [![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)
 [![Forks][forks-shield]][forks-url]
 [![Stargazers][stars-shield]][stars-url]
@@ -19,10 +21,10 @@
   <p align="center" style="font-size:30px; margin-top: 10px; margin-left: 10px">OSCSA</p>
 </div>
 
-<h1 align="center">Massive Open Online Courses (MOOCs) for Open Science in Arabic</h1>
+<h1 align="center">Open Innovation Lab</h1>
 
 <div align="center">
-    Massive Open Online Courses (MOOCs) for Open Science in Arabic that include videos, MCQ questions and written resources!
+    Massive Open Online Courses (MOOCs) for Open Science in Arabic
 </div>
 <br />
 
@@ -33,162 +35,141 @@
     <br />
     <a href="https://oscsa-moocs.netlify.app/">View Demo</a>
     ·
+    <a href="https://github.com/Open-Science-Community-Saudi-Arabia/MOOCs">Github</a>
+    ·
     <a href="https://github.com/Open-Science-Community-Saudi-Arabia/MOOCs/issues">Report Bug</a>
     ·
     <a href="https://github.com/Open-Science-Community-Saudi-Arabia/MOOCs/issues">Request Feature</a>
   </p>
 </div>
 
-## Deployment
-Frontend: https://oscsa-moocs.netlify.app/
-
-## Technologies
-
-### Frontend Technologies
-
-| Technology         | Version | Use                  |
-| ------------------ | ------- | -------------------- |
-| `Prettier`         | v2.7.1  | Code Formatting      |
-| `React`            | v18.2.0 | Frontend Framework   |
-| `NodeJs`           | v14     | Environment          |
-| `EsLint`           | v8.2.0  | Code Linting         |
-| `Vite`             | v2.6.8  | Code Bundler         |
-
-### Backend Technologies
-
-| Technology              | Version | Use                         |
-| ----------------------- | ------- | --------------------------- |
-| `NodeJS`                | v4.3    | Backend Environment         |
-| `ExpressJS`             | v3.10   | Framework for building APIs |
-| `MongoDB`               |    -    | Non-Relational Database     |
+<div align="justify">
 
+## Introduction
+[Open Science Community Saudi Arabia (OSCSA)](https://osc-ksa.com) was establised in line with Saudi Arabia's Vision 2030, which focuses on installing values, enhancing knowledge and improving equal access to education. It aims to provide a placec where new comers and experienced peers interact, inspire each other to embed open science practives and values in their workflows and provide feedback on policies, infrastructures and support services. Our community is part of the [International Network of Open Science & Scholarship Communities (INOSC)](https://osc-international.com).
 
-## Contributing :two_hearts:
-- If you like it, leave your star in this project :star2:
-- If you would like to complain/suggest/contribute to this project, feel free to open a issue :heart_decoration:
-- Please follow our [contributing guidelines](https://github.com/Open-Science-Community-Saudi-Arabia/MOOCs/blob/main/CONTRIBUTING.md).
-- This is the guide to how the UI Design should look when implementing any frontend pages. [Click this link to see the figma design](https://www.figma.com/file/mkhBuJAS2arzy3wrbTZp2D/Simple-Landing-page-for-OSCSA%2C-with-Log-In-and-Sign-Up-Pages?node-id=0%3A1) 
+Open Innovation lab is a Massive Open Online Courses (MOOCs) platform, where free online courses and materials are available to enrol. We have developed our own materials and will also include materials from Open Life Sciences and Turing Way. 
+The platform is similar to [Udemy](https://udemy.com), where a user can view videos and written materials as lessons.
 
 ## Getting Started
+This documentation is built using the [JSDoc](https://github.com/jsdoc/jsdoc) tool, an API documentation generator for JavaScript and [DocStrap](https://github.com/docstrap/docstrap) theme was used for the style. For more information about using JSDoc, see the [documentation](https://jsdoc.app/) guide or the [Get Started guide](https://jsdoc.app/about-getting-started.html)
+
+### Prerequisites
+To get started with contributing to Open Innovation Lab, you will need;
+- A Github [account](https://github.com/)
+- A basic understanding of Markdown is recommended but not necessary. Here is a [guide](https://www.markdownguide.org/cheat-sheet/)
+
+### Installation
+The project repository is distributed into two main directories `CLIENT` and `API`. The setup process for the Client and API are quite similar.
+
+Follow these steps:
+1. Create a fork of the [Open Innovation Lab github repository](https://github.com/Open-Science-Community-Saudi-Arabia/MOOCs) to your github account.
+2. Clone the forked repository to your local machine.
+   To do this run:
+   ```bash
+   git  clone https://github.com/<your-github-username>/MOOCs
+   ```
+3. Now you can make your contributions, commit them, push and raise a Pull request for the changes.
+   <i><b>NOTE:</b> Before making any contributions, make sure to go through the [Contribution guidelines](), it covers project specific rules for creating issues, and raising pull requests or any other form of contribution. </i>
+
+To setup the Client app locally follow these steps;
+#### Frontend setup
+1. Open your terminal inside the project's root directory
+2. Make sure to have node installed by running the following command
+    ```bash
+    node -v 
+    ```
+    This should display your current node version if it exists.
+    If you don't have [NodeJs](https://nodejs.org/) already installed follow the instructions [here](https://nodejs.org/en/download/)
+3. Install [yarn](https://www.npmjs.com/package/yarn) if you don't have it. Follow the installation guide [here](https://classic.yarnpkg.com/en/docs/install)
+4. From the projects root directory, navigate to the `Frontend` folder
+   ```bash
+   cd Frontend
+   ```
+5. Install necessary dependencies, run
+   ```bash
+   yarn install
+   ```
+6. To start the server, run
+   ```bash
+   yarn dev
+   ```
+    You're all set, open http://localhost:5173 to view the hosted proj
+
+#### Backend setup
+1. Open your terminal inside the project's root directory
+2. Make sure to have node installed, you can check by running
+   ```bash
+   node -v
+   ```
+   This should display your current node version if it's already installed.
+   If you don't have [NodeJs](https://nodejs.org/) already installed follow the instructions [here](https://nodejs.org/en/download/)
+3. Install [npm](https://docs.npmjs.com/about-npm), if you don't have npm installed follow the installation guide [here](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+4. Navigate to the `backend_API` folder
+   ```bash
+   cd backend_API  
+   ```
+5. Install necessary dependencies, run
+   ```bash
+   npm install
+   ```
+6. There are different environments, each environment has an independent configuration file withing the `/backend_API/src/` directory
+   `.env` will be used when you use the `production` environment
+   `.env.dev` will be used when you use the `dev` environment
+   `.env.test` will be used when you use the `test` environment
+7. To start the development server, run
+    ```bash
+    npm run dev
+    ```
+You're all set, all http requests can be sent to http://localhost:5000, except you specify the PORT variable in the `.env.dev` file
+You can refer to the detailed guide in the [Environment Setup Guide]()
+
+
+### Usage
+The frontend app uses [Yarn](https://classic.yarnpkg.com/en/docs/install) as its package manager and [React](https://reactjs.org/) as its frontend framework. The backend API uses [npm](https://npmjs.com) as its package manager, it also uses [Express](https://expressjs.com/) as its web framework and [MongoDB](https://www.mongodb.com/) as its database.
+
+**NOTE:** The frontend app is hosted on [Netlify](https://www.netlify.com/) and the backend API is hosted on [Heroku](https://www.heroku.com/) and [MongoDB Atlas](https://www.mongodb.com/cloud/atlas)
+
+**Starting the frontend app**
+1. Within the `/Frontend` directory, run
+   ```bash
+   yarn install
+   ```
+2. To start the development server, run
+   ```bash
+    yarn dev
+    ```
+3. To build the app for production, run
+   ```bash
+    yarn build
+    ```
+4. To start the production server, run
+    ```bash
+    yarn start
+    ```
+
+.
+
+
+**Starting the backend API**
+
+1. Within the `/backend_API` directory, you'll have to install all the necessary dependencies, run
+   ```bash
+   npm install
+   ```  
+
+2. To start the development server, run
+   ```bash
+    npm run dev
+    ```
+
+**NOTE:** The `.env.dev` file is used when you start the development server, you can change the environment variables in this file to suit your needs.
+The main environment variables required for starting up the API development server are:
+- PORT: The port number the server will listen to
+- MONGO_URI: The URI of the MongoDB database
+Other environment variables are optional, you can refer to the [Environment Setup Guide]() for more information.
 
-### Environment Setup
-
-- Make sure you have nodejs installed by running the following command:
-
-```bash
-node -v
-```
-
-- If the output is not the version of your nodejs installation, install nodejs from [here](https://nodejs.org/en/download/)
-
-*Things to note*
-- Linting has been set up for staged commits in the repository.
-- We're using `eslint` for js linting, and `prettier` for code formating.
-- Please make it a point to install `eslint` and `prettier` plugins on vscode to aid in your coding process.
-- Your code has to be properly formatted and have the correct syntax for you to be able to commit your changes.
-- Make sure you attend to all warnings and errors before you commit your code
-
-### Setting up the Frontend
-
-- Open `Git Bash` terminal inside root project folder
-- cd into the frontend folder by typing
-
-```bash
-cd Frontend
-```
-
-- After ensuring you've installed nodejs install [yarn](https://www.npmjs.com/package/yarn).
-- To install dependencies, run the following command:
-
-```bash
-yarn install
-```
-
-
-### STARTING THE SERVER
-
-- To start the whole application server
-
-```bash
-yarn dev
-```
-
-- Open [http://localhost:5173](http://localhost:5173) with your browser to see the result.
-- You're all set. Happy coding😁
-
-### Creating a production building
-
-```bash
-yarn build
-```
-
-### Checking formatting of whole project
-
-- Run this script to check if all files meet prettier standard rules of formatting
 
-```bash
-yarn format:check
-```
-
-- Run this script to fix all auto-fixable formatting errors in the whole project
-
-```bash
-yarn format:fix
-```
-
-### Checking code syntax is in line with eslint rules
-
-- Run this script to check if all files meet eslint standard rules of code sytax
-
-```bash
-yarn lint:check
-```
-
-- Run this script to fix all auto-fixable syntax errors in the whole project
-
-```bash
-yarn lint:fix
-```
-
-## Things to note as you contribute
-
-- Any page you code has to be responsive.
-- Write clear and concise commit messages.
-- Always run `yarn` after pulling code from the upstream repository.
-- Always, **Always** make pull requests to the **dev_team2** branch, not the `main` branch. All pull requests to the `main` branch will not be merged.
-- Please, always test your code and make sure it works correctly before making a pull request
-- Run `prettier --check "input name of file here"` to check if your code is well formatted before you commit
-- Run `eslint input name of file here --color` to check if the files you edited con form to the standards required for this project
-
-### Setting up Backend
-
-Instructions on how to run the backend server:
-
-- Open `Git Bash` terminal inside root project folder
-- cd into the backend folder by typing
-
-```bash
-cd backend_API
-```
-
-- To install dependencies, run the following command:
-
-```bash
-npm install
-```
-
-- create a .env file in the project folder with the `MONGO_URI`, `PORT` variables
-
-#### STARTING THE SERVER
-
-- To start the whole application server
-
-```bash
-npm run dev
-```
-
-- Open your browser on localhost with the port you specified to see the result.
-- You're all set and ready to code😁
 
 ## License
 
@@ -223,13 +204,19 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
   </tbody>
 </table>
 
+<!-- <div class="next-button"> -->
+
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
 
+<button class="next"> <a href="./docs/tutorials/api_docs.md"> Next </a> <button>
+</div>
+
 <!-- MARKDOWN LINKS & IMAGES -->
 <!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
 [cc-by]: http://creativecommons.org/licenses/by/4.0/