Contribution Guide (#37)

* Removed packages imported during dev stage.

* Added Contribution Guide to the README

* Proper code formating, changed security config img

Co-authored-by: milancurcic <[email protected]>

DESIGN.md

@@ -0,0 +1,135 @@
+# The Fortran Playground Design
+
+This document describes the design of the software that implements the Fortran
+Playground.
+Currently covered is the design of the frontend component of the system.
+The design of the backend will be documented in a later update.
+
+The playground consists of a frontend built using React which communicates with
+a Flask App responsible for executing user codes in a sandboxed environment
+using a Docker Container. 
+
+## Frontend
+
+There are various components which handle different parts of the website.
+All the styling is done using React-Bootstrap components. 
+
+### Editor
+
+We use an Ace Editor port for React called
+[React-Ace](https://github.com/securingsincity/react-ace).
+All information about Editor settings is stored under `frontend/src/Editor.js`.
+The editor settings are passed down as props to the react-ace component and
+offer various configuration options check
+[this page](https://securingsincity.github.io/react-ace/) to experiment with
+different parameters.
+For example, to change the theme import it from react-ace library:
+```
+import "ace-builds/src-noconflict/theme-github";
+```
+and change the theme prop inside `Editor.js`.
+
+### Navbar
+
+The navbar is configured under `frontend/src/Navbar.js`.
+It uses the default bootstrap navbar component.
+
+### Tutorial
+
+The content for tutorial is stored inside the tutorial.json file, which is
+generated by the backend from `tutorial.yml` file.
+A tutorial part consists of 3 sections- a title, content inside it and the code
+for the respective exercise.
+To add a new exercise append the three parameters inside the file at
+`src/backend/tutorial.yml`, e.g.:
+
+```
+- title: Heading for exercise
+  content: A breif explanation for the topic
+  code: "Code for the exercise"
+```
+
+Restart the server so it can compile the yaml into a JSON.
+The changes will be immediately reflected.
+To update the tutorial you can commit this JSON to the main repository via a
+pull request. 
+
+Please make sure that you configure the code properly with proper string
+formatting.
+This can be done by entering the code inside the editor first and copying the
+outputted "code" parameter inside the POST request.
+This also ensures your code works properly. 
+
+The tutorial is handled by the `TutorialCard` component insidde
+`src/TutorialCard.js` with respective props for Heading and Title.
+The change for code happens automatically by the `tutFunc` function inside
+`App.js` bounded by the switching buttons. 
+
+### InputBox
+
+The InputBox is a separate component which has props passed down from `App.js`
+to effectively manage state for the input.
+
+### App
+
+The source file `frontend/src/App.js` houses all of our states and major
+functionalities (API Calls, Library Selection).
+
+1. States:
+  * Text: Code inside the editor.
+  * Output: Output the is received from the backend after execution on container. 
+  * Input: User input for the code that is to be executed
+  * Exercise: Current exercise the user is on
+  There are also states which hold information on status for various toggleable
+  elements on the site:
+  * isLoading: Spinner until output is received from API
+  * inputOn: Input box button toggle
+  * showTutorial: Prompt for the quickstart tutorial 
+  * show: Pop up modal for library selection
+  * stdlibOn: State that manages whether stdlib has been selected by user or not
+2. Buttons for the tutorial are managed by `goRight` and `goLeft` functions,
+  they iterate on the tutorial.json using `exercise` state.
+3. API: POST Request to the backend server is done via `handleClick` function.
+  The request contains 3 parameters code, the input for it and the libraries
+  selected by the user.
+  The response from this request is stored in the output state.
+4. Custom styling from buttons is stored under the style tag inside run-button
+  class.
+5. The Output Section is inside the terminal class.
+   All elements in this section are made via Bootstrap Cards.
+   The Tutorial Card Component is also inside the terminal class. 
+6. The Modal Pop up for library selection is also a part of this section.
+  It holds the switches for libraries toggle.
+7. To add a new library in the frontend, add a new `<Form.Check>` component
+  with appropriate props and create a new state for the library.
+  For example:
+  ```
+  const [packageOn, ispackageOn] = useState(false)
+  ```
+  ```
+  <Form.Check
+      type="switch"
+      id="custom-switch"
+      label="library-name"
+      onChange{onLibSelect}
+      checked={packageOn} />
+  ```
+  Then create a new `onLibSelect` function as follows:
+  ```
+  const onLibSelect = () => {
+    setpackageOn(!packageOn);
+    if(!packageOn){
+      libs.push("library-name")
+    }
+    else{
+      if(libs.includes("library-name")){
+        libs = libs.filter(item => item !== "library-name")
+
+      }
+    }
+  ```
+
+### Styling
+
+The styling for the app is defined in `frontend/src/App.css`.
+All styles are applied from a single CSS file.

README.md

@@ -1,11 +1,12 @@
 # The Fortran Playground
 
 This is an interactive Fortran playground in the browser.
-It's main purpose is for newcomers to easily get a taste for the language
+Its main purpose is for newcomers to easily get a taste for the language
 and learn the essentials of Fortran programming.
 
 Follow the instructions below if you want to run the Fortran Playground server
 on your own computer.
+For the design of the software, see [this document](DESIGN.md).
 
 ## Getting started
 
@@ -96,7 +97,7 @@ curl \
   --request POST '127.0.0.1:5000/run' \
   --header 'Content-Type: application/json' \
   --data-raw '{
-    "code": "program hello\r\n  ! This is a comment line; it is ignored by the compiler\r\n  print *, 'Hello, World!'\r\nend program hello\r\n",
+    "code": "program hello\r\n  print *, 'Hello, World!'\r\nend program hello\r\n",
     "programInput": "",
     "libs" : []
 }'
@@ -105,7 +106,7 @@ curl \
 If everything is set up correctly so far, you should get the following response:
 
 ```
-{"executed":" Hello World New Line\n Hello Mars\n"}
+{"executed":" Hello, World!\n"}
 ```
 
 ### Set up the frontend server

frontend/src/Editor.js

@@ -1,9 +1,7 @@
 import React from "react";
 import AceEditor from "react-ace";
 
-import "ace-builds/src-noconflict/mode-java";
 import "ace-builds/src-noconflict/mode-fortran";
-import "ace-builds/src-noconflict/theme-github";
 import "ace-builds/src-noconflict/theme-monokai";
 import "ace-builds/src-noconflict/ext-language_tools";