Create usage manual (#73)

Closes #63 

Co-authored-by: Vishwak Srinivasan <[email protected]>
Co-authored-by: Prateek Kumar <[email protected]>
Co-authored-by: Vaibhav Sinha <[email protected]>

.vscode/settings.json

@@ -7,4 +7,5 @@
   "python.linting.pylintEnabled": false,
   "python.linting.mypyEnabled": true,
   "files.insertFinalNewline": true,
+  "restructuredtext.confPath": "${workspaceFolder}/docs/source",
 }

README.md

@@ -1,6 +1,6 @@
 # [autojudge: An Online Judge for Coding contests](https://github.com/vbsinha/autojudge)
 
-[![CircleCI](https://circleci.com/gh/vbsinha/autojudge.svg?style=svg)](https://circleci.com/gh/vbsinha/autojudge)
+[![CircleCI](https://circleci.com/gh/vbsinha/autojudge.svg?style=svg)](https://circleci.com/gh/vbsinha/autojudge) [![Documentation Status](https://readthedocs.org/projects/autojudge/badge/?version=latest)](https://autojudge.readthedocs.io/en/latest/?badge=latest)
 
 ---
 This is an implementation of an online judge that can be used for conducting programming contests as well as managing assignments in a university.
@@ -9,41 +9,21 @@ Apart from the facilities of usual programming contest portals, this portal prov
 
 These additional features include: Instructor (Problem poster) grades above judge scores, soft and hard deadlines for assignments including penalties, customizable compilation and test script, linter scores et cetera.
 
-Currently, the judge supports 3 languages: C, C++, Python, but this list can be extended easily.
+Currently, the judge supports 5 languages: C, C++, Python, Go and Haskell but this list can be extended easily.
 
-## Pre-requisites
+## Requirements
 
-To run this application, you will require **Python 3.6 or above**. While we tested this primarily with Python 3.6 or above, we expect it to work for other Python versions > 3.
+To run this application, you will require **Python 3.6 or above**. While we tested this primarily with Python 3.6 or above, we expect it to work for other Python versions > 3 that support Django 2.2.2.
 
-We have used **Django 2.2** to build this application. Additionally, we use **social-auth-app-django** for authentication purposes. **Docker** is used to run and evaluate submissions.
+Other primary requirements are specified in [requirements.txt](requirements.txt). To setup documentation locally, please check the requirements specified in [docs/requirements.txt](docs/requirements.txt).
 
-## Running the application
+## Setting up and running the application
 
-- Open a terminal instance and clone the repository using:
-```bash
-git clone https://github.com/vbsinha/autojudge
-```
+The instructions to setup and run this application are specified in our [documentation](https://autojudge.readthedocs.io/en/latest/usage.html).
 
-- Enter the folder by:
-```bash
-cd autojudge/
-````
+## Understanding how `autojudge` works
 
-- Create and apply database migrations in Django with the following commands:
-```bash
-python manage.py makemigrations
-python manage.py migrate
-```
-
-- To run the server locally, enter:
-```bash
-python manage.py runserver
-```
-
-- Open the application on your browser at `localhost:8000`.
-  - Please note that certain elements of the application require a working internet connection. It is recommended that this application is used with a working internet connection for this reason.
-
-- Run the `submission_watcher_saver.py` program using `python submission_watcher_saver.py`. This program is responsible for running and scoring the submissions on the Docker image. This program can be started at any time after the server has started, but it is preferred that the program be kept running in parallel with the server.
+If you are interested in understanding how `autojudge` works, please find the API documentation [here](https://autojudge.readthedocs.io/en/latest/api.html).
 
 ## License
 

autojudge/settings_production.py

@@ -1,5 +1,5 @@
 # To use these settings during development, run with
-# python manage.py runserver --settings=autojudge.settings_production
+# python manage.py runserver --settings=autojudge.settings_production.py
 
 import os
 from typing import List
@@ -9,10 +9,20 @@
 DEBUG = False
 
 # Edit/Add the settings during deployment
-ALLOWED_HOSTS: List[str] = ['autojudge.iith.ac.in']
+ALLOWED_HOSTS: List[str] = ['autojudge.com']
 
-# Confiure Postgresql as database
+# Configure PostgreSQL as database
 # https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-DATABASES
 
 # Configure static root and static url
 # https://docs.djangoproject.com/en/2.2/howto/static-files/deployment/#serving-static-files-in-production
+STATIC_ROOT = 'static_files'
+STATIC_URL = 'https://static.autojudge.com/'
+
+# Security
+SECURE_CONTENT_TYPE_NOSNIFF = True
+SECURE_BROWSER_XSS_FILTER = True
+SECURE_SSL_REDIRECT = True
+SESSION_COOKIE_SECURE = True
+X_FRAME_OPTIONS = 'DENY'
+CSRF_COOKIE_SECURE = True

docs/source/index.rst

@@ -1,8 +1,18 @@
 Welcome to autojudge's documentation!
 =====================================
 
+Setting up and running ``autojudge``
+------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   usage
+
+The internals of the ``judge`` app in ``autojudge``
+---------------------------------------------------
+
 .. toctree::
    :maxdepth: 1
 
-   tutorial
    api

docs/source/usage.rst

@@ -0,0 +1,111 @@
+Using ``autojudge``
+===================
+
+``autojudge`` is a tool developed for automating evaluation for code submission in coding contests and in assigments at college. For your convenience, we have split this usage manual into 3 phases.
+
+Phase 1 : Get ``autojudge`` and set up your environment
+-------------------------------------------------------
+
+Phase 1a: Getting ``autojudge``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``autojudge`` is available on GitHub, and you can download a version of your choice from the `releases page <https://github.com/vbsinha/autojudge/releases>`_. We prefer that you use the latest version.
+
+Extract the compressed files and you now have ``autojudge`` ready to use.
+
+If you are a fan of ``master``, then clone the repository, either using ``git`` or by downloading from GitHub from `here <https://github.com/vbsinha/autojudge>`__.
+
+Phase 1b: Setting up your environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The evaluation of submissions are conducted on a Docker image that is built while initializing the application. Please install Docker using the instructions provided on `their installation page <https://docs.docker.com/install/linux/docker-ce/ubuntu>`__.
+
+If you are very conservative about populating your default environment with random Python packages, create a virtual environment for installing some *new* packages either using ``virtualenv`` or ``conda-env``.
+
+Install the requirements specified in |requirements.txt|_. Don't forget to activate your environment if you have one.
+
+.. |requirements.txt| replace:: ``requirements.txt``
+.. _requirements.txt: ../../../requirements.txt
+
+If you going to deploy ``autojudge``, please install PostgreSQL using the instructions provided on `their installation page <https://www.postgresql.org/download/linux/ubuntu/>`__.
+
+Phase 2 : Run ``autojudge``
+---------------------------
+
+Activate your environment.
+
+Create and apply database migrations in Django with the following commands:
+
+.. code:: bash
+
+    python manage.py makemigrations
+    python manage.py migrate
+
+There are two ways of using ``autojudge``.
+
+Development
+~~~~~~~~~~~
+
+To run ``autojudge`` locally:
+
+.. code:: bash
+
+    python manage.py runserver
+
+Go to ``localhost:8000`` in your favourite browser. Keep yourself connected to internet for full functionality as certain frontend support such as JavaScript scripts are pulled from the internet.
+
+The program |submission_watcher_saver.py|_ scores the submissions serially in the chronological order of submissions. It can be started anytime after the server has started, but it is preferred that the program be kept running in parallel with the server. Run it using:
+
+.. |submission_watcher_saver.py| replace:: ``submission_watcher_saver.py``
+.. _submission_watcher_saver.py: ../../../submission_watcher_saver.py
+
+.. code:: bash
+
+    python submission_watcher_saver.py
+
+
+Production
+~~~~~~~~~~
+
+The procedure to deploy ``autojudge`` is different from running locally. Below are a series of steps that will help you deploy ``autojudge``.
+
+Set the environmental variable ``AUTOJUDGE_SECRET_KEY`` to a random string, which should not be exposed to anyone. Think of it to be a private key.
+
+Now modify a few more settings to |settings_production.py|_. The first is to setup the database. We suggest using a PostgreSQL database. This modification can be done by adding the below dictionary to |settings_production.py|_. Modify the values ``NAME``, ``USER``, ``PASSWORD``, ``HOST`` and ``PORT`` accordingly.
+
+.. code:: python
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.postgresql',
+            'NAME': 'mydatabase',  # Sample
+            'USER': 'mydatabaseuser',  # Sample
+            'PASSWORD': 'mypassword',  # Sample
+            'HOST': '127.0.0.1',  # Sample
+            'PORT': '5432',  # Sample
+        }
+    }
+
+
+Next we setup the ``STATIC_ROOT`` path, the location where you would like the static files to be generated. This has to be set in |settings_production.py|_.
+
+To generate the static files, run:
+
+.. code:: bash
+
+    python manage.py collectstatic --settings=autojudge.settings_production.py
+
+The static files are generated in the path specified by ``STATIC_ROOT`` previously. 
+
+Now host the static files on a server and configure the URL in ``STATIC_URL`` in |settings_production.py|_. If you have hosted the generated static files at https://static.autojudge.com, then change the ``STATIC_URL`` to https://static.autojudge.com/ (note the trailing slash is required).
+
+You could optionally setup a cache server. Instructions to do this are specified `here <https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-CACHES>`__.
+
+Configure the security settings in |settings_production.py|_ (leave it to the default values if you will be hosting on ``https``).
+
+.. |settings_production.py| replace:: ``settings_production.py``
+.. _settings_production.py: ../../../autojudge/settings_production.py
+
+To configure the Apache server using ``WSGI``, follow the instructions `here <https://docs.djangoproject.com/en/2.2/howto/deployment/wsgi/>`__.
+
+And finally, set environment variable ``DJANGO_SETTINGS_MODULE`` to ``autojudge.settings_production`` as opposed to ``autojudge.settings`` which is present by default.

requirements.txt

@@ -0,0 +1,4 @@
+Django==2.2.2
+social-auth-app-django==3.1.0
+pycodestyle==2.5.0
+typing==3.6.4