diff options
Diffstat (limited to 'yaksh')
32 files changed, 782 insertions, 335 deletions
diff --git a/yaksh/documentation/conf.py b/yaksh/documentation/conf.py index 10ad210..1a2c50f 100644 --- a/yaksh/documentation/conf.py +++ b/yaksh/documentation/conf.py @@ -59,7 +59,7 @@ master_doc = 'index' # General information about the project. project = u'Yaksh' -copyright = u'2016, FOSSEE' +copyright = u'2018, FOSSEE' author = u'FOSSEE' # The version info for the project you're documenting, acts as replacement for @@ -67,9 +67,9 @@ author = u'FOSSEE' # built documents. # # The short X.Y version. -version = u'0.1.2' +version = u'0.7' # The full version, including alpha/beta/rc tags. -release = u'July 2016' +release = u'Feb 2018' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/yaksh/documentation/images/add_exercise.jpg b/yaksh/documentation/images/add_exercise.jpg Binary files differnew file mode 100644 index 0000000..2512f1a --- /dev/null +++ b/yaksh/documentation/images/add_exercise.jpg diff --git a/yaksh/documentation/images/add_lesson.jpg b/yaksh/documentation/images/add_lesson.jpg Binary files differnew file mode 100644 index 0000000..6de272c --- /dev/null +++ b/yaksh/documentation/images/add_lesson.jpg diff --git a/yaksh/documentation/images/add_question.jpg b/yaksh/documentation/images/add_question.jpg Binary files differindex 791ba79..b9b5bc7 100644 --- a/yaksh/documentation/images/add_question.jpg +++ b/yaksh/documentation/images/add_question.jpg diff --git a/yaksh/documentation/images/add_quiz.jpg b/yaksh/documentation/images/add_quiz.jpg Binary files differindex 780a179..3264684 100644 --- a/yaksh/documentation/images/add_quiz.jpg +++ b/yaksh/documentation/images/add_quiz.jpg diff --git a/yaksh/documentation/images/course_details_features.jpg b/yaksh/documentation/images/course_details_features.jpg Binary files differindex 5e820f9..63b4b2e 100644 --- a/yaksh/documentation/images/course_details_features.jpg +++ b/yaksh/documentation/images/course_details_features.jpg diff --git a/yaksh/documentation/images/course_features.jpg b/yaksh/documentation/images/course_features.jpg Binary files differindex 12853af..2da356e 100644 --- a/yaksh/documentation/images/course_features.jpg +++ b/yaksh/documentation/images/course_features.jpg diff --git a/yaksh/documentation/images/cpp_standard_testcase.jpg b/yaksh/documentation/images/cpp_standard_testcase.jpg Binary files differindex 8d3161f..cfb1d89 100644 --- a/yaksh/documentation/images/cpp_standard_testcase.jpg +++ b/yaksh/documentation/images/cpp_standard_testcase.jpg diff --git a/yaksh/documentation/images/create_course.jpg b/yaksh/documentation/images/create_course.jpg Binary files differnew file mode 100644 index 0000000..bcf1eff --- /dev/null +++ b/yaksh/documentation/images/create_course.jpg diff --git a/yaksh/documentation/images/design_course.jpg b/yaksh/documentation/images/design_course.jpg Binary files differnew file mode 100644 index 0000000..287ebea --- /dev/null +++ b/yaksh/documentation/images/design_course.jpg diff --git a/yaksh/documentation/images/design_module.jpg b/yaksh/documentation/images/design_module.jpg Binary files differnew file mode 100644 index 0000000..eda8825 --- /dev/null +++ b/yaksh/documentation/images/design_module.jpg diff --git a/yaksh/documentation/images/design_questionpaper.jpg b/yaksh/documentation/images/design_questionpaper.jpg Binary files differindex fdadcdb..05da597 100644 --- a/yaksh/documentation/images/design_questionpaper.jpg +++ b/yaksh/documentation/images/design_questionpaper.jpg diff --git a/yaksh/documentation/images/embed_video.jpg b/yaksh/documentation/images/embed_video.jpg Binary files differnew file mode 100644 index 0000000..84d18a2 --- /dev/null +++ b/yaksh/documentation/images/embed_video.jpg diff --git a/yaksh/documentation/images/float_testcase.jpg b/yaksh/documentation/images/float_testcase.jpg Binary files differindex 2b6827c..70b8a9f 100644 --- a/yaksh/documentation/images/float_testcase.jpg +++ b/yaksh/documentation/images/float_testcase.jpg diff --git a/yaksh/documentation/images/hook_testcase.jpg b/yaksh/documentation/images/hook_testcase.jpg Binary files differindex 3018050..4d404f6 100644 --- a/yaksh/documentation/images/hook_testcase.jpg +++ b/yaksh/documentation/images/hook_testcase.jpg diff --git a/yaksh/documentation/images/integer_testcase.jpg b/yaksh/documentation/images/integer_testcase.jpg Binary files differindex ca70a41..58ff6be 100644 --- a/yaksh/documentation/images/integer_testcase.jpg +++ b/yaksh/documentation/images/integer_testcase.jpg diff --git a/yaksh/documentation/images/java_standard_testcase.jpg b/yaksh/documentation/images/java_standard_testcase.jpg Binary files differindex a5af3fc..c13f618 100644 --- a/yaksh/documentation/images/java_standard_testcase.jpg +++ b/yaksh/documentation/images/java_standard_testcase.jpg diff --git a/yaksh/documentation/images/moderator_dashboard.jpg b/yaksh/documentation/images/moderator_dashboard.jpg Binary files differindex 13ce524..739d221 100644 --- a/yaksh/documentation/images/moderator_dashboard.jpg +++ b/yaksh/documentation/images/moderator_dashboard.jpg diff --git a/yaksh/documentation/images/python_standard_testcase.jpg b/yaksh/documentation/images/python_standard_testcase.jpg Binary files differindex 992e805..a4d2ac8 100644 --- a/yaksh/documentation/images/python_standard_testcase.jpg +++ b/yaksh/documentation/images/python_standard_testcase.jpg diff --git a/yaksh/documentation/images/questions.jpg b/yaksh/documentation/images/questions.jpg Binary files differindex 780d729..1935541 100644 --- a/yaksh/documentation/images/questions.jpg +++ b/yaksh/documentation/images/questions.jpg diff --git a/yaksh/documentation/images/stdio_testcase.jpg b/yaksh/documentation/images/stdio_testcase.jpg Binary files differindex 41a1694..9a041ba 100644 --- a/yaksh/documentation/images/stdio_testcase.jpg +++ b/yaksh/documentation/images/stdio_testcase.jpg diff --git a/yaksh/documentation/images/string_testcase.jpg b/yaksh/documentation/images/string_testcase.jpg Binary files differindex 7286eff..6cd2b72 100644 --- a/yaksh/documentation/images/string_testcase.jpg +++ b/yaksh/documentation/images/string_testcase.jpg diff --git a/yaksh/documentation/images/view_lessons.jpg b/yaksh/documentation/images/view_lessons.jpg Binary files differnew file mode 100644 index 0000000..4229afe --- /dev/null +++ b/yaksh/documentation/images/view_lessons.jpg diff --git a/yaksh/documentation/images/view_modules.jpg b/yaksh/documentation/images/view_modules.jpg Binary files differnew file mode 100644 index 0000000..5b535d3 --- /dev/null +++ b/yaksh/documentation/images/view_modules.jpg diff --git a/yaksh/documentation/images/view_quizzes.jpg b/yaksh/documentation/images/view_quizzes.jpg Binary files differnew file mode 100644 index 0000000..43bb36f --- /dev/null +++ b/yaksh/documentation/images/view_quizzes.jpg diff --git a/yaksh/documentation/index.rst b/yaksh/documentation/index.rst index a790357..db48544 100644 --- a/yaksh/documentation/index.rst +++ b/yaksh/documentation/index.rst @@ -2,10 +2,6 @@ Welcome to Yaksh's documentation! ================================= Yaksh lets user create and take online programming quiz. Yaksh is an open source project developed by FOSSEE. The code is available on `github <https://github.com/fossee/online_test>`_. - -.. note:: - - This is a basic documentation for users to get comfortable with the interface. The documentation is still under progress. The user documentation for the site is organized into a few sections: diff --git a/yaksh/documentation/installation.rst b/yaksh/documentation/installation.rst index e4ec581..1c90997 100644 --- a/yaksh/documentation/installation.rst +++ b/yaksh/documentation/installation.rst @@ -12,67 +12,311 @@ Installing Yaksh **For installing Yaksh** - 1. **Clone the repository**:: + 1. **Clone the repository**:: $ git clone https://github.com/FOSSEE/online_test.git - 2. **Go to the online_test directory**:: + 2. **Go to the online_test directory**:: - $ cd ./online_test + $ cd ./online_test - 3. **Install the dependencies** - - * For Python 2 use:: + 3. **Install the dependencies** - + * For Python 2 use:: - $ pip install -r ./requirements/requirements-py2.txt + $ pip install -r ./requirements/requirements-py2.txt - * For Python 3 (recommended) use:: + * For Python 3 (recommended) use:: - $ pip install -r ./requirements/requirements-py3.txt + $ pip install -r ./requirements/requirements-py3.txt Quick Start ----------- 1. **Start up the code server that executes the user code safely**: - * To run the code server in a sandboxed docker environment, run the command:: + * To run the code server in a sandboxed docker environment, run the command:: - $ invoke start + $ invoke start - .. note:: + .. note:: - Make sure that you have Docker installed on your system beforehand. - Find docker installation guide `here <https://docs.docker.com/engine/installation/#desktop>`_. + Make sure that you have Docker installed on your system beforehand. + Find docker installation guide `here <https://docs.docker.com/engine/installation/#desktop>`_. - * To run the code server without docker, locally use:: + * To run the code server without docker, locally use:: - $ invoke start --unsafe + $ invoke start --unsafe - .. note:: + .. note:: - Note this command will run the yaksh code server locally on your machine and is susceptible to malicious code. You will have to install the code server requirements in sudo mode. + Note this command will run the yaksh code server locally on your machine and is susceptible to malicious code. You will have to install the code server requirements in sudo mode. 2. **On another terminal, run the application using the following command** - * To start the django server:: + * To start the django server:: - $ invoke serve + $ invoke serve - .. note:: + .. note:: - The serve command will run the django application server on the 8000 port and hence this port will be unavailable to other processes. + The serve command will run the django application server on the 8000 port and hence this port will be unavailable to other processes. 3. **Open your browser and open the URL** - ``http://localhost:8000/exam`` 4. **Login as a teacher to edit the quiz or as a student to take the quiz** - - * Credentials: - For Student: - * Username: student - * Password: student - For Teacher: - * Username: teacher - * Password: teacher + + * Credentials: + For Student: + * Username: student + * Password: student + For Teacher: + * Username: teacher + * Password: teacher 5. **User can also login to the Default Django admin by going to URL and entering the following admin credentials** ``http://localhost:8000/admin`` - For admin: - * Username: admin - * Password: admin + For admin: + * Username: admin + * Password: admin + + +Production Deployment +--------------------- + +* **Deploying Locally** + + Follow these steps to deploy locally on the server. + + * **Pre-Requisite** + + 1. Ensure `pip <https://pip.pypa.io/en/latest/installing.html>`__ is + installed + 2. Install dependencies, Run; + + :: + + pip install -r requirements/requirements-py2.txt # For Python 2 + + pip3 install -r requirements/requirements-py3.txt # For Python 3 + + 3. Install MySql Server + 4. Install Python MySql support + 5. Install Apache Server for deployment + + 6. Create a database named ``yaksh`` by following the steps below + + :: + + $> mysql -u root -p + $> mysql> create database yaksh + + 7. Add a user named ``yaksh_user`` and give access to it on the database + ``yaksh`` by following the steps below + + :: + + mysql> grant usage on yaksh to yaksh_user@localhost identified + by 'mysecretpassword'; + + mysql> grant all privileges on yaksh to yaksh_user@localhost; + + 8. Add ``DATABASE_PASSWORD = 'mysecretpassword'`` and + ``DATABASE_USER = 'yaksh_user'`` to online\_test/settings.py + + + * **Installation & Usage** + + To install this app follow the steps below: + + 1. Clone this repository and cd to the cloned repo. + + :: + + $ git clone https://github.com/FOSSEE/online_test.git + + 2. Rename the ``.sampleenv`` to ``.env`` + + 3. In the ``.env`` file, uncomment the following and replace the values (please keep the remaining settings as is); + + :: + + DB_ENGINE=mysql # Or psycopg (postgresql), sqlite3 (SQLite) + DB_NAME=yaksh + DB_USER=root + DB_PASSWORD=mypassword # Or the password used while creating a Database + DB_PORT=3306 + + 4. Run: + + :: + + $ python manage.py makemigrations yaksh + + $ python manage.py migrate yaksh + + 5. Run the python server provided. This ensures that the code is + executed in a safe environment. Do this like so: + + :: + + $ sudo python -m yaksh.code_server # For Python 2.x + + + $ sudo python3 -m yaksh.code_server # For Python 3.x + + Put this in the background once it has started since this will not + return back the prompt. It is important that the server be running + *before* students start attempting the exam. Using sudo is necessary + since the server is run as the user "nobody". This runs the number + ports configured in the settings.py file in the variable + "N\_CODE\_SERVERS". The "SERVER\_TIMEOUT" also can be changed there. + This is the maximum time allowed to execute the submitted code. Note + that this will likely spawn multiple processes as "nobody" depending + on the number of server ports specified. + + You can also use a Dockerized code server, see `Dockerized Code Server` + + + 6. The ``wsgi.py`` script should make it easy to deploy this using + mod\_wsgi. You will need to add a line of the form: + + :: + + WSGIScriptAlias / "/online_test/wsgi.py" + + to your apache.conf. For more details see the Django docs here: + + https://docs.djangoproject.com/en/2.0/howto/deployment/wsgi/ + + 7. Create a Superuser/Administrator: + + :: + + python manage.py createsuperuser + + 8. Go to http://desired\_host\_or\_ip:desired\_port/exam + + And you should be all set. + + 9. Note that the directory "output" will contain directories, one for + each user. Users can potentially write output into these that can be + used for checking later. + + 10. As a moderator you can visit http://desired\_host\_or\_ip/exam/monitor to view results and user data interactively. You could also "grade" the papers manually if needed. + +.. _dockerized-code-server: + +* **Using Dockerized Code Server** + + 1. Install + `Docker <https://docs.docker.com/engine/installation/>`__ + + 2. Go to the directory where the project is located + + :: + + cd /path/to/online_test + + 3. Create a docker image. This may take a few minutes, + + :: + + docker build -t yaksh_code_server -f ./docker/Dockerfile_codeserver + + 4. Check if the image has been created using the output of ``docker + images`` + + 5. Run the invoke script using the command ``invoke start`` The command + will create and run a new docker container (that is running the + code\_server.py within it), it will also bind the ports of the host + with those of the container + + 6. You can use ``invoke --list`` to get a list of all the available commands + + + .. _deploying-multiple-dockers: + + +* **Deploying Multiple Dockers** + + Follow these steps to deploy and run the Django Server, MySQL instance and Code Server in seperate Docker instances. + + 1. Install `Docker <https://docs.docker.com/engine/installation/>`__ + + 2. Install `Docker Compose <https://docs.docker.com/compose/install/>`__ + + 3. Rename the ``.sampleenv`` to ``.env`` + + 4. In the ``.env`` file, uncomment all the values and keep the default values as is. + + 5. Go to the ``docker`` directory where the project is located: + + :: + + cd /path/to/online_test/docker + + 6. Build the docker images + + :: + + invoke build + + 7. Run the containers and scripts necessary to deploy the web + application + + :: + + invoke begin + + 8. Make sure that all the containers are ``Up`` and stable + + :: + + invoke status + + 8. Run the containers and scripts necessary to deploy the web + application, ``--fixtures`` allows you to load fixtures. + + :: + + invoke deploy --fixtures + + 10. Stop the containers, you can use ``invoke restart`` to restart the containers without removing them + + :: + + invoke halt + + 11. Remove the containers + + :: + + invoke remove + + 12. You can use ``invoke --list`` to get a list of all the available commands + + + .. _add-commands: + +* **Additional commands available** + + We provide several convenient commands for you to use: + + - load\_exam : load questions and a quiz from a python file. See + docs/sample\_questions.py + + - load\_questions\_xml : load questions from XML file, see + docs/sample\_questions.xml use of this is deprecated in favor of + load\_exam. + + - results2csv : Dump the quiz results into a CSV file for further + processing. + + - dump\_user\_data : Dump out relevalt user data for either all users + or specified users. + + For more information on these do this: + + :: + + $ python manage.py help [command] + + where [command] is one of the above. diff --git a/yaksh/documentation/moderator_dashboard.rst b/yaksh/documentation/moderator_dashboard.rst index a93ea3c..4b5bfea 100644 --- a/yaksh/documentation/moderator_dashboard.rst +++ b/yaksh/documentation/moderator_dashboard.rst @@ -14,4 +14,5 @@ The following pages explain the various functions available for moderators moderator_docs/creating_course.rst moderator_docs/creating_quiz.rst moderator_docs/creating_question.rst + moderator_docs/creating_lessons_modules.rst moderator_docs/other_features.rst
\ No newline at end of file diff --git a/yaksh/documentation/moderator_docs/creating_course.rst b/yaksh/documentation/moderator_docs/creating_course.rst index d4dc5f8..5aaddf5 100644 --- a/yaksh/documentation/moderator_docs/creating_course.rst +++ b/yaksh/documentation/moderator_docs/creating_course.rst @@ -3,26 +3,30 @@ Courses ======= For students to take a quiz, it is imperative for the moderator to create a course first. +A course can contain several modules and a module can contain several lessons and/or quizzes. + +To create modules, lessons and quizzes go to the :doc:`creating_lessons_modules` +and :doc:`creating_quiz` section of the documentation. Setting up a new course ----------------------- To create a course, click on the Add New Course button on the moderator's dashboard. This will lead you to a create add course page, where you need to fill in the following fields. - .. image:: ../images/create_course.png + .. image:: ../images/create_course.jpg - * Name + * **Name** Name of the Course - * Enrollment + * **Enrollment** Open enrollment is open to all students. Enroll Request requires students to send a request which the moderator can accept or reject. - * Active + * **Active** If the course should be active for students to take the quiz. The status of the course can be edited later. - * Code + * **Code** If the course should be hidden and only accessible to students possessing the correct course code. - * Instructions + * **Instructions** Instructions for the course - * Start Date and Time for enrollment of course + * **Start Date and Time for enrollment of course** If the enrollment of the course should be available only after a set date and time - * End Date and Time for enrollment of course + * **End Date and Time for enrollment of course** If the enrollment of the course should be available only before a set date and time @@ -37,21 +41,77 @@ Features in Courses The following features are available for courses - * Course Name - Clicking on course name link will display all the enrolled, rejected and requested students list. Moderator can accept or reject the student. - * Quiz Name - Clicking on the quiz name will let you edit the quiz. - * Question Paper - Click on the **Add** link to create a Question Paper for associated Quiz. - If a question paper is already created, click on the Question Paper link to edit question paper. - * Add Teacher - Clicking on Add teacher can let you add teachers for the course. The teachers can edit and modify only the specific course that are allotted to them. - * Teachers added to the course + * **Course Name** + Click on course name link to view all the enrolled, rejected and requested students list. Moderator can accept or reject the student. + * **Module Name** + Click to edit a module added to the course + * **Lesson or Quiz Name** + Click to edit a Lesson or Quiz added to the course + + In edit quiz you can also attempt the quiz in two modes - + * **God Mode** - In God mode you can attempt quiz without any time or eligibilty constraints. + * **User Mode** - In user mode you can attempt quiz the way normal users will attempt i.e. + + * Quiz will have the same duration as that of the original quiz. + * Quiz won't start if the course is inactive or the quiz time has expired. + * **Add Quizzes/Lessons for <module-name>** + Click to add/delete lessons or quizzes. + * **Design Course** + Click to add/delete modules of a course. + * **Add Teacher** + Click to add teachers for the course. The teachers can edit and modify only the specific course that are allotted to them. + * **Clone Course** + Click to create a copy of a course along with its modules, lessons and quizzes. + * **Teachers added to the course** This shows all the teachers added to a particular course. - * Download CSV for the entire course + * **Download CSV for the entire course** This downloads the CSV file containing the performance of all students in every quiz for a given course. - * Edit Course - Clicking on the edit course button will let you edit the details of an existing course. + * **Edit Course** + Click to edit the details of an existing course. + * **Deactivate/Activate Course** + Click to deactivate or activate the course. + * **My Courses** + Click to show all the courses created by you. + * **Allotted courses** + Click to view all the courses allotted to you. + * **Add New Course** + Click to open course form to create new course. + * **Add/View Quizzes** + Click to view all the quizzes created by you or add new quiz. + * **Add/View Lessons** + Click to view all the lessons created by you or add new lesson. + * **Add/View Modules** + Click to view all the modules created by you or add new module. + + +Design a Course +--------------- + + Clicking on **Design Course** will show the below page. + + .. image:: ../images/design_course.jpg + + **Available Modules** contains all the modules that are not added to a course. + + To add a module to the course select the checkbox besides the desired module to be added and click **Add to course** button. + + **Chosen Modules** contains all the modules that are added to a course. + + Following parameters can be changed while designing a course: + + **Order** - Order in which modules are shown to a student. + + To change a module's order change the value to a desired order in the textbox under **Order** column and click **Change order**. + + **Check Prerequisite** - Check if previous module is completed. Default value is **Yes**. + For e.g., Assuming a course contains modules **Demo Module** and **Python module** in the given order; a student has to first complete **Demo module** to attempt **Python Module** if the **Check Prerequisite** value for **Python Module** is checked **Yes**. + + **Currently** column shows the current value of **Check Prerequisite** which in this case is **Yes**. + + Select the checkbox from **Change** column under **Check Prerequisite** and click **Change Prerequisite** button to change the value. + + To remove a module from the course select the checkbox beside every module and click **Remove from course** button. + Features in Course Details -------------------------- @@ -62,17 +122,15 @@ Features in Course Details Following are the features for course details - - * Requests + * **Requests** This is a list of students who have requested to be enrolled in the course. Moderator can enroll or reject selected students. - * Enrolled + * **Enrolled** This is a list of students who have been enrolled in the course. Moderator can reject enrolled students. - * Rejected + * **Rejected** This is a list of students who have been rejected for enrollment in a course. Moderator can enroll rejected students. - * Deactivate/Activate Course - Clicking on this will deactivate or activate the course. - * Upload Users + * **Upload Users** Create and enroll users automatically by uploading a csv of the users. The mandatory fields for this csv are - **firstname, lastname, email**. Other fields like **username, password, institute, roll_no, department, remove** fields are optionals. - * Clone Course - This will create a clone of the course for the moderator. - * Send Mail + * **Send Mail** Moderator can send mail to all enrolled students or selected students. + * **View Course Status** + View students' progress through the course. diff --git a/yaksh/documentation/moderator_docs/creating_lessons_modules.rst b/yaksh/documentation/moderator_docs/creating_lessons_modules.rst new file mode 100644 index 0000000..5131dd1 --- /dev/null +++ b/yaksh/documentation/moderator_docs/creating_lessons_modules.rst @@ -0,0 +1,91 @@ +.. _creating_lessons_modules: + +=================== +Lessons and Modules +=================== + +Courses can have lessons and quizzes encapsulated using a module. + + * **What is a lesson?** + A lesson can be any markdown text with/or an embedded video of a particular topic. + + * **What is a module?** + A Module is a collection of lessons and courses clubbed together by similar idea/content. A module can have its own description as a markdown text with/or an embedded video. + + +Setting up a Lesson +----------------------- + + To create a new lesson or edit any existing lesson click on **Add/View Lessons** from courses page. + + .. image:: ../images/view_lessons.jpg + + This page shows all the lessons created by you. + + Click on **Add new Lesson** to add new lesson. Click on the **lesson name** to edit a lesson. + + .. image:: ../images/add_lesson.jpg + + * **Name** - Name of the lesson. + * **Description** - Description can be any markdown text or embedded video link. + * **Active** - Activate/Deactivate a lesson + * **Lesson files** - Add files to the lesson which will be available for students to view and download. All the uploaded files will be shown below. + + Click on **Save** to save a lesson. + + Click on **Preview Lesson Description** to preview lesson description. Markdown text from the description is converted to html and is displayed below. + + Select the checkbox beside each uploaded file and click on **Delete files** to remove files from the lesson. + + Click on **Embed Video Link** to embed a video. On clicking a pop-up will be shown. + + .. image:: ../images/embed_video.jpg + + Enter the url and click on **Submit** a html div is generated in the text area below. + Click on the button below the textarea to copy the textarea content. This html div can then be added in the lesson description. + + +Setting up a Module +----------------------- + + To create a new module or edit any existing module click on **Add/View Modules** from courses page. + + .. image:: ../images/view_modules.jpg + + This page shows all the modules created by you. + + Creating a new module or editing an existing module is similar to a lesson creation with a difference that a module has no option to upload files. + + +Design a Module +--------------- + + To add lessons or quizzes to a module click on **Add Quizzes/Lessons for <module-name>**. + + .. image:: ../images/design_module.jpg + + **Available Lessons and quizzes** contains all the lessons and quizzes that are not added to a module. + + To add a lesson or a quiz to the module select the checkbox beside every lesson or quiz and click **Add to Module** button. + + **Choosen Lesson and quizzes** contains all the lessons and quizzes that are added to a module. + + A lesson or quiz added to a module becomes a unit. A unit has following parameters to change: + + **Order** - Order in which units are shown to a student. + + To change a unit's order change the value in the textbox under **Order** column and click **Change order**. + + **Check Prerequisite** - Check if previous unit is completed. Default value is **Yes**. + For e.g. A student has to first complete **Yaksh Demo quiz** to attempt **Demo Lesson** if the **Check Prerequisite** value for **Demo Lesson** is checked **Yes**. + + **Currently** column shows the current value of **Check Prerequisite** which in this case is **Yes**. + + Select the checkbox from **Change** column under **Check Prerequisite** and click **Change Prerequisite** button to change the value. + + To remove a lesson or a quiz from the module select the checkbox beside every lesson or quiz and click **Remove from Module** button. + + + + + diff --git a/yaksh/documentation/moderator_docs/creating_question.rst b/yaksh/documentation/moderator_docs/creating_question.rst index 78b6f2c..82bb6e5 100644 --- a/yaksh/documentation/moderator_docs/creating_question.rst +++ b/yaksh/documentation/moderator_docs/creating_question.rst @@ -5,315 +5,356 @@ Questions Setting up questions -------------------- - Setting up questions is the most important part of the Yaksh experience. Questions can be of multiple types i.e Multiple choice questions (MCQ), Multiple correct choices (MCC), Coding questions and assignment upload types. + Setting up questions is the most important part of the Yaksh experience. Questions can be of multiple types i.e Multiple choice questions (MCQ), Multiple correct choices (MCC), Coding questions, assignment upload, fill in the blanks. - To set up a question click on the questions link in the navigation bar. + To set up a question click on the questions link in the navigation bar. - .. image:: ../images/questions.jpg - - To add a question click on the **Add Question** button + .. image:: ../images/questions.jpg + + To add a question click on the **Add Question** button - .. image:: ../images/add_question.jpg + .. image:: ../images/add_question.jpg - * **Summary**- Summary or the name of the question. + * **Summary**- Summary or the name of the question. - * **Language** - Programming language on which the question is based. + * **Language** - Programming language on which the question is based. - * **Type** - Type of the question. i.e Multiple Choice, Multiple Correct Choice, Code and Assignment Upload. + * **Type** - Type of the question. i.e Multiple Choice, Multiple Correct Choice, Code, Assignment Upload etc. - * **Points** - Points is the marks for a question. + * **Points** - Points is the marks for a question. - * **Description** - The actual question description is to be written. + * **Description** - The actual question description in HTML format. - .. note:: To add code snippets in questions please use html <code> and <br> tags. + .. note:: To add code snippets in questions please use html <code> and <br> tags. - * **Tags** - Type of label or metadata tag making it easier to find specific type of questions. + * **Tags** - Type of label or metadata tag making it easier to find specific type of questions. - * **Snippet** - Snippet is used to give any default value or default code or command. This will be displayed in the students answer form. This is used only for code questions. + * **Solution** - Add solution for the question. - * **Partial Grading** - Click this checkbox to enable partial grading feature. + * **Snippet** - Snippet is used to give any default value or default code or command. This will be displayed in the students answer form. This is used only for code questions. - * **File** - File field is used to upload files if there is any file based question. - For e.g. The question is reading a file say **dummy.txt** and print its content. - You can then upload a file **dummy.txt** which will be available to the student while attempting the quiz. + * **Minimum time(in minutes)** - This value can be set for questions which will be added to a Exercise. Exercise time will depend on this time. - * Some file features: - 1. To delete a file click the delete checkbox and click on Delete Selected Files button. - 2. To extract a file for e.g. say **dummy.zip** click the extract checkbox and click on Save button. - If **extract** is selected, the file will be extracted while checking - the student submitted code. - 3. To hide any file from student click the hide checkbox and click on Save button. + * **Partial Grading** - Click this checkbox to enable partial grading feature. - .. Note:: We only support **zip** extension for **extract file** feature. + * **Grade Assignment Upload** - Click this checkbox if the assignment upload based question needs evaluation. Evaluation is done with **Hook based TestCase** only. + + * **File** - File field is used to upload files if there is any file based question. + For e.g. The question is reading a file say **dummy.txt** and print its content. + You can then upload a file **dummy.txt** which will be available to the student while attempting the quiz. + + * Some file features: + 1. To delete a file click the delete checkbox and click on **Delete Selected Files button**. + 2. To extract a file for e.g. say **dummy.zip** click the extract checkbox and click on Save button. + If **extract** is selected, the file will be extracted while checking + the student submitted code. + 3. To hide any file from student click the hide checkbox and click on Save button. + + .. Note:: We only support **zip** extension for **extract file** feature. How to write Test cases ----------------------- - - The following explains different methods to write test cases. - - * **Create Standard Test Case** - - Select Standard from Add Test Case field. - - * For Python: - .. image:: ../images/python_standard_testcase.jpg - :width: 80% - - In the test case field write a python assert to check the user code. - For e.g. :: - - assert add(1, 2) == 3 - - for program of addition. - - * For C, C++, Java and Bash: - Sample Moderator code - - For C and C++: - .. image:: ../images/cpp_standard_testcase.jpg - :width: 80% - - Consider a Program to add three numbers. - The code in the Test case field should be as follows: :: - - #include <stdio.h> - #include <stdlib.h> - - extern int add(int, int, int); - - template <class T> - void check(T expect,T result) - { - if (expect == result) - { - printf("\nCorrect:\n Expected %d got %d \n",expect,result); - } - else - { - printf("\nIncorrect:\n Expected %d got %d \n",expect,result); - exit (1); - } - } - - int main(void) - { - int result; - result = add(0,0,0); - printf("Input submitted to the function: 0, 0, 0"); - check(0, result); - result = add(2,3,3); - printf("Input submitted to the function: 2, 3, 3"); - check(8,result); - printf("All Correct\n"); - } - - Assuming Students answer to be as below: :: - - int add(int a, int b, int c) - { - return a+b+c; - } - - .. Note:: 1. In the above example, **add** in the main function is obtained from student code. - 2. Please make sure that the student code function and testcase calling function should be same which in this case is **add**. - - For Java: - .. image:: ../images/java_standard_testcase.jpg - :width: 80% - - Consider a Program to find square of a number. - The code in the Test case Field should be as follows: :: - class main - { - public static <E> void check(E expect, E result) - { - if(result.equals(expect)) - { - System.out.println("Correct:\nOutput expected "+expect+" and got "+result); - } - else - { - System.out.println("Incorrect:\nOutput expected "+expect+" but got "+result); - System.exit(1); - } - } - public static void main(String arg[]) - { - Test t = new Test(); - int result, input, output; - input = 0; output = 0; - result = t.square_num(input); - System.out.println("Input submitted to the function: "+input); - check(output, result); - input = 5; output = 25; - result = t.square_num(input); - System.out.println("Input submitted to the function: "+input); - check(output, result); - input = 6; output = 36; - result = t.square_num(input); - System.out.println("Input submitted to the function: "+input); - check(output, result); - } - } - - Assuming Students answer to be as below: :: - - class Test - { - int square_num(int num) - { - return num*num; - } - } - - .. Note:: 1. For Java, class name should always be **main** in testcase. - - 2. In the above example, **Test** is the class of student's code. - 3. Please make sure that the student's code class and calling class in testcase is always **Test**. (square_num is the function inside Test class.) - - For Bash: - .. image:: ../images/bash_standard_testcase.jpg - :width: 80% - - In **Test case** Field write your bash script. - For e.g. the question is to move to a particular directory and read a file - **test.txt** - The Test case code shown is: :: - - #!/bin/bash - cd $1 - cat $2 - - In **Test case args** Field type your Command line arguments. - - In this case the test case args are: :: - - somedata/ test.txt - - .. Note:: 1. **Test case args** field is used only for bash. - 2. Each argument should be separated by **space**. - 3. This field can be left blank. - - - Check Delete Field if a test case is to be removed. - - Finally click on Save to save the test case. - - - * **Create Standard Input/Output Based Test Case** + + The following explains different methods to write test cases. + + * **Create Standard Test Case** + + Select Standard from Add Test Case field. Sample Testcases are given for all + languages. + + * **For Python:** + .. image:: ../images/python_standard_testcase.jpg + :width: 80% + + In the test case field write a python assert to check the user code. + For e.g. :: + + assert add(1, 2) == 3 + + for program of addition. + + * **For C, C++:** + + .. image:: ../images/cpp_standard_testcase.jpg + :width: 80% + + Consider a Program to add three numbers. + The code in the Test case field should be as follows: :: + + #include <stdio.h> + #include <stdlib.h> + + extern int add(int, int, int); + + template <class T> + void check(T expect,T result) + { + if (expect == result) + { + printf("\nCorrect:\n Expected %d got %d \n",expect,result); + } + else + { + printf("\nIncorrect:\n Expected %d got %d \n",expect,result); + exit (1); + } + } + + int main(void) + { + int result; + result = add(0,0,0); + printf("Input submitted to the function: 0, 0, 0"); + check(0, result); + result = add(2,3,3); + printf("Input submitted to the function: 2, 3, 3"); + check(8,result); + printf("All Correct\n"); + } + + Assuming Students answer to be as below: :: + + int add(int a, int b, int c) + { + return a+b+c; + } + + .. Note:: 1. In the above example, **add** in the main function is obtained from student code. + 2. Please make sure that the student code function and testcase calling function should be same which in this case is **add**. + + * **For Java:** + .. image:: ../images/java_standard_testcase.jpg + :width: 80% + + Consider a Program to find square of a number. + The code in the Test case Field should be as follows: :: + + class main + { + public static <E> void check(E expect, E result) + { + if(result.equals(expect)) + { + System.out.println("Correct:\nOutput expected "+expect+" and got "+result); + } + else + { + System.out.println("Incorrect:\nOutput expected "+expect+" but got "+result); + System.exit(1); + } + } + public static void main(String arg[]) + { + Test t = new Test(); + int result, input, output; + input = 0; output = 0; + result = t.square_num(input); + System.out.println("Input submitted to the function: "+input); + check(output, result); + input = 5; output = 25; + result = t.square_num(input); + System.out.println("Input submitted to the function: "+input); + check(output, result); + input = 6; output = 36; + result = t.square_num(input); + System.out.println("Input submitted to the function: "+input); + check(output, result); + } + } + + Assuming Students answer to be as below: :: + + class Test + { + int square_num(int num) + { + return num*num; + } + } + + .. Note:: 1. For Java, class name should always be **main** in testcase. + + 2. In the above example, **Test** is the class of student's code. + 3. Please make sure that the student's code class and calling class in testcase is always **Test**. (square_num is the function inside Test class.) + + * **For Bash:** + .. image:: ../images/bash_standard_testcase.jpg + :width: 80% + + In **Test case** Field write your bash script. + For e.g. the question is to move to a particular directory and read a file + **test.txt** + The Test case code shown is: :: + + cd $1 + cat $2 + + In **Test case args** Field type your Command line arguments. + + In this case the test case args are: :: + + somedata/ test.txt + + .. Note:: 1. **Test case args** field is used only for bash. + 2. Each argument should be separated by **space**. + 3. This field can be left blank. + + + Check Delete Field if a test case is to be removed. + + Finally click on Save to save the test case. + + + * **Create Standard Input/Output Based Test Case** - Select StdIO from Add Test Case field. + Select StdIO from Add Test Case field. + + .. image:: ../images/stdio_testcase.jpg + :width: 80% + + In Expected input field, enter the value(s) that will be passed to the students' code through a standard I/O stream. + + .. note:: If there are multiple input values in a test case, enter the values in new line. + + In Expected Output Field, enter the expected output for that test case. For e.g type 3 if the output of the user code is 3. + + Setting up Standard Input/Output Based questions is same for all languages. - .. image:: ../images/stdio_testcase.jpg - :width: 80% + * **Create MCQ or MCC Based Test Case** - In Expected input field, enter the value(s) that will be passed to the students' code through a standard I/O stream. + Select MCQ/MCC from Add Test Case field. - .. note:: If there are multiple input values in a test case, enter the values in new line. + Fig (a) showing MCQ based testcase - In Expected Output Field, enter the expected output for that test case. For e.g type 3 if the output of the user code is 3. + .. image:: ../images/mcq_testcase.jpg + :width: 80% - Setting up Standard Input/Output Based questions is same for all languages. + Fig (b) showing MCC based testcase - * **Create MCQ or MCC Based Test Case** + .. image:: ../images/mcc_testcase.jpg + :width: 80% - Select MCQ/MCC from Add Test Case field. + In Options Field type the option check the correct checkbox if the current option is correct and click on Save button to save each option. - Fig (a) showing MCQ based testcase + For MCC based question, check the correct checkbox for multiple correct options. - .. image:: ../images/mcq_testcase.jpg - :width: 80% + * **Create Hook based Test Case** - Fig (b) showing MCC based testcase + Select Hook from Add Test Case field. - .. image:: ../images/mcc_testcase.jpg - :width: 80% + In Hook based test case type, moderator is provided with a evaluator function + called **check_answer** which is provided with a parameter called **user_answer**. - In Options Field type the option check the correct checkbox if the current option is correct and click on Save button to save each option. + **user_answer** is the code of the student in string format. - For MCC based question, check the correct checkbox for multiple correct options. + .. note :: For assignment upload type question there will be no **user answer** File uploaded by student will be the answer. - * **Create Hook based Test Case** + Suppose the student needs to upload a file say **new.txt** as assignment. + Sample Hook code for this will be as shown below. :: - Select Hook from Add Test Case field. + def check_answer(user_answer): + ''' Evaluates user answer to return - + success - Boolean, indicating if code was executed correctly + mark_fraction - Float, indicating fraction of the weight to a test case + error - String, error message if success is false - In Hook based test case type, moderator is provided with a evaluator function - called **check_answer** which is provided with a parameter called **user_answer**. + In case of assignment upload there will be no user answer ''' - **user_answer** is the code of the student in string format. + success = False + err = "Incorrect Answer" # Please make this more specific + mark_fraction = 0.0 - A moderator can check the string for specific words in the user answer - and/or compile and execute the user answer (using standard python libraries) to - evaluate and hence return the mark fraction. + try: + with open('new.txt', 'r') as f: + if "Hello, World!" in f.read(): + success = True + err = "Correct Answer" + mark_fraction = 1.0 + else: + err = "Did not found string Hello, World! in file." + except IOError: + err = "File new.txt not found." + return success, err, mark_fraction - .. image:: ../images/hook_testcase.jpg - :width: 80% + A moderator can check the string for specific words in the user answer + and/or compile and execute the user answer (using standard python libraries) to + evaluate and hence return the mark fraction. - * **Create Integer Based Test Case** - Select **Answer in Integer** from Type field. + .. image:: ../images/hook_testcase.jpg + :width: 80% - Select Integer from Add Test Case field. + * **Create Integer Based Test Case** - In the Correct field, add the correct integer value for the question. + Select **Answer in Integer** from Type field. - .. image:: ../images/integer_testcase.jpg - :width: 80% + Select Integer from Add Test Case field. - * **Create String Based Test Case** + In the Correct field, add the correct integer value for the question. - Select **Answer in String** from Type field. + .. image:: ../images/integer_testcase.jpg + :width: 80% - Select **String** from Add Test Case field. + * **Create String Based Test Case** - In the **Correct** field, add the exact string answer for the question. + Select **Answer in String** from Type field. - In **String Check** field, select if the checking of the string answer - should be case sensitive or not. + Select **String** from Add Test Case field. - .. image:: ../images/string_testcase.jpg - :width: 80% + In the **Correct** field, add the exact string answer for the question. - * **Create Float Based Test Case** + In **String Check** field, select if the checking of the string answer + should be case sensitive or not. - Select **Answer in Float** from Type field. + .. image:: ../images/string_testcase.jpg + :width: 80% - Select **Float** from Add Test Case field. + * **Create Float Based Test Case** - In the **Correct** field, add the correct float value for the question. + Select **Answer in Float** from Type field. - In the **Error Margin** field, add the margin of error that will be allowed. + Select **Float** from Add Test Case field. - .. image:: ../images/float_testcase.jpg - :width: 80% + In the **Correct** field, add the correct float value for the question. + + In the **Error Margin** field, add the margin of error that will be allowed. + + .. image:: ../images/float_testcase.jpg + :width: 80% Features in Question -------------------- - - * **Download Questions** + + * **Download Questions** - Select questions from the list of questions displayed on the Questions page. Click on the Download Selected button to download the questions. This will create a zip file of the Questions selected. + Select questions from the list of questions displayed on the Questions page. Click on the Download Selected button to download the questions. This will create a zip file of the Questions selected. - * **Upload Questions** - - Click on the browse button. This will open up a window. Select the zip file of questions and click Ok and then click on Upload file button, questions will be uploaded and displayed on the Questions page. + * **Upload Questions** + + Click on the browse button. This will open up a window. Select the zip file of questions and click Ok and then click on Upload file button, questions will be uploaded and displayed on the Questions page. - Zip file should contain **questions_dump.yaml** from which questions will be loaded. - Zip file can contain files related to questions. + Zip file should contain **questions_dump.yaml** from which questions will be loaded. + Zip file can contain files related to questions. - * **Test Questions** - - Select questions from the list of question displayed on the Questions page. Click on Test selected button. This will take you to a quiz with the selected questions. + * **Test Questions** + + Select questions from the list of question displayed on the Questions page. Click on Test selected button. This will take you to a quiz with the selected questions. + + .. Note:: This will not create an actual quiz but a trial quiz. This quiz is hidden from the students and only for moderator to view. You can delete the quiz from moderator's dashboard. + + * **Filter Questions** + + You can filter questions based on type of question, language of question or marks of question. + 1. Click Select Question Type to filter question based on type of the question. + 2. Click Select Language to filter question based on language of the question. + 3. Click Select marks to filter question based on mark of the question. - .. Note:: This will not create an actual quiz but a trial quiz. This quiz is hidden from the students and only for moderator to view. You can delete the quiz from moderator's dashboard. + * **Search by tags** - * **Filter Questions** - - You can filter questions based on type of question, language of question or marks of question. - 1. Click Select Question Type to filter question based on type of the question. - 2. Click Select Language to filter question based on language of the question. - 3. Click Select marks to filter question based on mark of the question. + 1. You can search the questions by tags added during question creation. + 2. Click on the Available tags to view all the available tags. Select any tag from available tags and click **Search**. + 3. Enter the tag in the search bar and click on **Search** respective questions will be displayed. diff --git a/yaksh/documentation/moderator_docs/creating_quiz.rst b/yaksh/documentation/moderator_docs/creating_quiz.rst index 3f227ef..8b93188 100644 --- a/yaksh/documentation/moderator_docs/creating_quiz.rst +++ b/yaksh/documentation/moderator_docs/creating_quiz.rst @@ -1,44 +1,68 @@ +.. _creating_quiz: + ======= Quizzes ======= Quizzes are intrinsically associated with a course, hence to view and/or edit a quiz, we need to navigate to the courses page. -In courses page click on **Add Quiz** button to create a new quiz. +Clicking on Add/View Quizzes from courses page will open the page as shown below + +.. image:: ../images/view_quizzes.jpg +This page shows all the quizzes and exercise created. Creating a Quiz --------------- + + Click on **Add New Quiz** button to add a quiz. + .. image:: ../images/add_quiz.jpg .. note :: It is important to have created or uploaded questions before creating a quiz. - In courses click on **Add Quiz** button to add a quiz. - - * **Course** - Select a course from Course field. This field is mandatory. * **Start Date and Time of quiz** - The date and time after which the quiz can be taken. * **End Date and Time of quiz** - The date and time after which the quiz is deactivated and cannot be attempted. * **Duration** - Duration of quiz to be written in minutes. - * **Active** - If the quiz is active or not. + * **Active** - Check the checkbox to activate/deactivate quiz. * **Description** - Description or name of the quiz. * **Passing Percentage** - Minimum percentage required to pass the test. - * **Prerequisite** - Set a prerequisite quiz to be passed before attempting the current quiz. - * **Language** - Programming language on which the quiz is based. * **Attempts allowed** - Number of attempts that a student can take of the current quiz. - * **Number of Days** - Number of days between attempts. + * **Time Between Quiz Attempts in hours** - For a quiz with multiple attempts this value can be set so that student can attempt again after the specified time. * **Instructions for students** - Additional instructions for students can be added. Some default instructions are already provided. * **Allow student to view answer paper** - Click on this checkbox to allow student to view their answer paper. + * **Allow student to skip questions** - Click on this checkbox to allow/disallow student to skip questions for a quiz. Value defaults to allow skipping questions. + * **Weightage** - Every quiz will have weightage depending on which grades will be calculated. Once a quiz parameters have been set click on **Save** button to save the quiz. -To create a Question paper, Click on **Add** link located besides the created quiz in courses page. +To create a Question paper, Click on **Add** link located besides the created quiz. + +Creating a Exercise +------------------- + + Click on **Add New Exercise** button to add a exercise. + + .. image:: ../images/add_exercise.jpg + + Exercise is similar to quiz with a difference that exercise has infinite attempts and + infinite time. It also does not allow a student to skip the question. + Each question in an exercise can be timed i.e. time to solve a particular question. + Once the question time expires, question solution is shown to the student. + + All the parameters are set by default only below parameters can be changed. + + * **Description** - Description or name of the exercise. + * **Allow student to view answer paper** - Click on this checkbox to allow student to view their answer paper. + * **Active** - Select the checkbox to activate/deactivate exercise. Default value is active. + Designing Question Paper ------------------------ .. image:: ../images/design_questionpaper.jpg - A quiz can have fixed as well as random questions. Fixed questions are those question that are bound to appear for every student taking the quiz. In random questions a pool of questions is given and number of questions to be picked from the pool is set. Hence for different students, different questions from the pool will appear. + A quiz/exercise can have fixed as well as random questions. Fixed questions are those question that are bound to appear for every student taking the quiz. In random questions a pool of questions is given and number of questions to be picked from the pool is set. Hence for different students, different questions from the pool will appear. To add questions to a questionpaper @@ -48,25 +72,17 @@ Designing Question Paper * Click on save question paper to save it or preview question paper to preview it. -Editing a Quiz --------------- - - In Courses page, click on the quiz link to edit the quiz. Then change the parameters and click on design question paper to save it. This will redirect you to the moderator dashboard. +Editing a Quiz/Exercise +----------------------- - In edit quiz you can also attempt the quiz in two modes - - * **God Mode** - In God mode you can attempt quiz without any time or eligibilty constraints. - * **User Mode** - In user mode you can attempt quiz the way normal users will attempt i.e. - - * Quiz will have the same duration as that of the original quiz. - * Quiz won't start if the course is inactive or the quiz time has expired. - * You will be notified about quiz prerequisites.(You can still attempt the quiz though) + Click on the quiz/exercise link to edit, change the parameters and click on Save. Editing a QuestionPaper ----------------------- - Click on the Question Paper for a Quiz link besides Quiz in courses page and follow steps from Design Question Paper. + Click on the Question Paper for a <Quiz-name/Exercise-name> besides Quiz/Exercise and follow steps from Design Question Paper. If the questions are already added to a Question Paper then they are shown in the **Fixed Questions currently in the paper** section. |
