Merge pull request #2 from ahujatejas06/cmd_pages

Made some cmd pages

_config.yml

@@ -1,10 +1,14 @@
 title: RAS-Backend Documentation
 description: A guide to understanding the backend server of RAS.
 theme: just-the-docs
+logo: "/assets/images/spoLogo.webp"
+
 callouts:
   info:
     title: Information
     color: green
+search:
+  button: true
   note: 
     title: Note
-    color: blue
+    color: blue

docs/cmd/admin.md

@@ -0,0 +1,53 @@
+---
+title : admin
+layout : default
+nav_order: 1
+parent : cmd
+---
+
+# admin.go
+
+
+
+The Go viper package is used to read the [config.yaml configuration constants file]() and get the port of the various administrator services. A new Go engine is initialized and the required middlewares are attached to it.
+
+
+## function adminRCServer
+It returns an http server instance for listening to requests of the mail service.
+
+{: .info} 
+The adminRC service is hosted on port 3490.
+
+### Middlewares Attached to the process
+- [CORS]() : Custom middleware to allow cross-origin requests.
+- [Authenticator]() : Custom middleware to get the role ID of the user using the service.
+- [EnsurePsuedoAdmin]() : Custom middleware to ensure that the role ID is that of a pseudo admin. (OPC, GOD, APC and Chairman)
+- Recovery
+- Logger
+
+Initialized service is passed to [adminRC router]().
+
+## function adminApplicationServer
+Same as [adminRCServer]() except the fact the service is passed to [Application admin router]().
+
+{: .info} 
+The adminApplication service is hosted on port 3492.
+
+## function adminCompanyServer
+Same as [adminRCServer]() except the fact the service is passed to [Company admin router]().
+
+{: .info} 
+The adminCompany service is hosted on port 3495.
+
+## function adminStudentServer
+Same as [adminRCServer]() except the fact the service is passed to [Student admin router]().
+
+{: .info} 
+The adminStudent service is hosted on port 3500.
+
+---
+#### References
+- [Go Engines]()
+- [Go Logger middleware]()
+- [Go recovery middleware]()
+- [Go Viper module]()

docs/cmd/auth.md

@@ -0,0 +1,33 @@
+---
+title : auth
+layout : default
+nav_order: 2
+parent : cmd
+---
+
+# auth.go
+
+This file configures the mail service handler for the authentication service.
+
+## function authServer
+It returns an http server instance of the started server for broadcasting content on the mail channel.
+
+The Go viper package is used to read the [config.yaml configuration constants file]() and get the port of the authentication service. A new Go engine is initialized and the required middlewares are attached to it.
+
+{: .info} 
+The authentication service is hosted on port 3475. 
+
+### Middlewares Attached to the process
+- CORS - Cross-Origin Resource Sharing : Custom middleware to allow cross-origin requests.
+- Recovery (Standard Go middleware) : to recover from any panic
+- Logger (Standard Go Middleware) : To log the status
+- Gin middleware
+
+Initialized service is passed to [auth router].
+
+---
+#### References
+- [Go Engines]()
+- [Go Logger middleware]()
+- [Go recovery middleware]()
+- [Go Viper module]()

docs/cmd/cmd.md

@@ -0,0 +1,31 @@
+---
+title : cmd
+layout : default
+nav_order: 7
+has_children: true
+---
+
+# main.go
+
+A mail service is initialized in a goroutine and passed on to the following handlers. The errors are returned to the main function and logged by the logger. 
+
+{: .info}
+Mail read and write API call timeouts are defined to 5 seconds and 10 seconds respectively. The mailer works instantly.
+
+The service is passed on to the following handlers. The handlers are defined in the [overview]({{ site.baseurl }}{% link docs/overview.md %}) for reference.
+
+- Auth
+- RAS
+- Student
+- Company 
+- Admin RC
+- Admin Application 
+- Admin Student
+- Admin Company
+
+---
+#### References
+- [chan - Go Command](https://www.sohamkamani.com/golang/channels/)
+- [errgroup](https://pkg.go.dev/golang.org/x/sync/errgroup)
+- [Go Routines](https://go.dev/tour/concurrency/1)
+- [Gin multiple port http services](https://github.com/gin-gonic/gin/issues/346)

docs/cmd/company.md

@@ -0,0 +1,9 @@
+---
+title : company
+layout : default
+nav_order: 3
+parent : cmd
+---
+
+# company.go
+Similar to other handler files, this file configures the mail service handler to be passed to the company router.

docs/cmd/ras.md

@@ -0,0 +1,12 @@
+---
+title : ras
+layout : default
+nav_order: 4
+parent : cmd
+---
+
+# ras.go
+Similar to other handler files, this file configures the mail service handler to be passed to the ras router.
+
+{: .info}
+The RAS service doesn't require authentication as is is just used to test the mail service and send a testing mail.

docs/cmd/student.md

@@ -0,0 +1,10 @@
+---
+title : student
+layout : default
+nav_order: 5
+parent : cmd
+---
+
+# student.go
+
+Similar to other handler files, this file configures the mail service handler to be passed to the student router.

docs/errors/errors.md

@@ -0,0 +1,9 @@
+---
+title : Logged Errors
+layout : default
+nav_order: 17
+has_children : true
+---
+
+# Common logged errors
+This file lists down the various common errors encountered while developing, building and deploying the application.

docs/mail.md

@@ -2,4 +2,55 @@
 title : mail
 layout : default
 nav_order: 11
----
+---
+# config.go 
+This file initializes the mailer with the required constants. Viper is used to get the constants from [_config.yml]() and the [secrets file](). Logrus is used to log the status.
+
+Following constants are initialized
+- user
+- sender : user + "@iitk.ac.in"
+- pass : password
+- host
+- port
+- webteam : email address of the web-team
+
+{: .info}
+user, password, webteam are defined in the secrets file.
+
+---
+# service.go
+This file defines methods to build messages. 
+
+Mail struct is defined with the standard mailing properties.
+- To
+- Subject
+- Body
+
+## Function BuildMessage
+This method builds the message by setting the From, Subject, To and Signature properties of the body of the mail and returns the final body.
+
+[Read the code here]()
+
+{: .info}
+All the recipients are put into BCC when the message is mass mailed.
+
+## Function Service
+This is the function started in [cmd]() as a Go routine for sending mails. The function receives the mail queue channel, builds the message of the mail using [BuildMessage function]() and sends the mail using the SMTP protocol.
+
+Errors are logged by logrus.
+
+{: .info}
+The mail is forwarded to the webteam mail as well
+
+--- 
+# generate.go
+This file takes all the properties of the mail and generates the final object of type Mail to be sent using the SMTP protocol.
+
+- **Function GenerateMail** - to generate a single mail
+- **Function GenerateMails** - to generate multiple mails
+
+---
+#### References
+- [logrus middleware](https://pkg.go.dev/github.com/sirupsen/logrus#section-readme)
+- [A Tour of Go](https://go.dev/tour/concurrency/1) - Do check this out
+- [SMTP Documentation](https://pkg.go.dev/net/smtp)

docs/overview.md

@@ -3,3 +3,31 @@ title : Overview
 layout: default
 nav_order: 2
 ---
+# Overview
+The application is divided into multiple sections and follows a sort of neomonolith architecture. The different sections of the application use separate ports for increased stability. A crash at one of the ports/handler leaves the others remain unaffected.
+
+## RAS: 3470
+This is the testing handler. It is used to get ping responses from the server. It is also used to test the connection to the mail controller.
+
+## AUTH: 3475
+This handler is responsible for authentication of the user. It is responsible for checking the credentials of the user and returning the appropriate response. It also handles the registration of new users.
+
+
+## STUDENT: 3480
+This handler has all the routes related to the student. It is responsible for handling the requests related to the student's application, profile, etc.
+
+## COMPANY: 3485
+This handler has all the routes related to the company. It is responsible for handling the requests related to the company's new job openings, notices, application status etc.
+
+# ADMIN:
+Overview of the admin handlers
+## RC: 3490
+This handler is responsible for handling the requests related to the RC. It is used by the admin to post notices, reminders, verify resumes and answers to rc questions.
+
+## APP: 3492
+This handler contains all the APIs related to the admin RC events, proformas, etc. It is used by the admin to verify the proforma, add new proforma, etc.
+## COMPANY: 3495
+This handler contains all the APIs related to the company. It is used by the admin to verify the company, add new company, etc.
+## STUDENT: 3500
+This handler contains all the APIs related to the student. It is used by the admin to verify the student, add new student, etc.
+

docs/util.md

@@ -2,4 +2,30 @@
 title : Utils
 layout : default
 nav_order: 16
----
+---
+
+# convert.go
+This file contains utilities to parse data as required in other parts of the program.
+
+Functions in the file
+- **ParseUint** - converts a string to an unsigned integer. Very standard implementation. If it cannot be converted, then 0 along with non-nil error is returned.
+
+{: .info}
+>2 objects are returned (converted unsigned integer, error).
+
+- **ParseString** - Converts an unsigned integer to string.
+
+---
+
+# prog_dept.go
+This file contains utilities to check and compare the program departments.
+
+**Function isDoubleMajor** to check if the given branch ID is a double major branch ID or not. (returns boolean) 
+
+{: .info }
+> array of all double major program department IDs
+> 
+>  28: AE	| 29: BSBE	| 30: CE	| 31: CHE	|
+>  32: CSE	| 33: EE	| 34: MSE	| 35: ME	|
+>  96: CHM	| 36: ECO	| 37: MTH	| 97: SDS	|
+>  98: PHY	|

index.md

@@ -3,5 +3,6 @@ title: Home
 layout: home
 nav_order: 1
 ---
-RAS-Backend Documentation
----
+## RAS Backend Documentation
+RAS is the Recruitment Automation System developed by a team of 10 undergraduate students for the Students' Placement Office, IIT Kanpur to ease-out and automate the internship and placement process of the institute.
+