Add docs for custom submit

docs/source/user_docs/exchange/base_exchange.rst

@@ -0,0 +1,106 @@
+.. _custom_exchange:
+
+=====================
+Personalized Exchange
+=====================
+
+`e2xgrader` comes with an optional custom exchange. The exchange provides personalized directories for each student.
+
+Activating the Exchange
+-----------------------
+
+To activate the exchange head over to the section about :ref:`configuring e2xgrader <configure_e2xgrader>`.
+
+Personalized Inbound
+--------------------
+
+The custom exchange can be configured to use a personalized inbound. 
+If this is activated, each student will have a personalized inbound directory.
+
+Assume you have the course *MyCourse* and the assignment
+*MyAssignment*. In the original nbgrader exchange the student
+will submit to :code:`<exchange_directory>/MyCourse/inbound/`.
+This will be the same for each student and causes a potential security 
+issue. If a student knows the name of the submission of another student,
+they can read their submission.
+
+If the personalized inbound is used, the student will submit to
+:code:`<exchange_directory>/MyCourse/personalized-inbound/<student_id>/`.
+This directory is only readable by the student.
+
+.. code-block:: python
+
+   # nbgrader_config.py
+
+   from e2xgrader.config import configure_base, configure_exchange
+
+   c = get_config()
+
+   # Register custom preprocessors for autograding and generating assignments
+   configure_base(c)
+
+   # Register custom exchange
+   configure_exchange(c)
+
+   # Activate the personalized inbound
+   c.Exchange.personalized_inbound = True
+
+Personalized Outbound
+---------------------
+
+If activated, the custom exchange uses a personalized outbound
+directory for each student.
+
+This allows for creating custom versions of an assignment per student.
+Students will fetch from 
+:code:`<exchange_directory>/MyCourse/outbound/MyAssignment/<student_id>/`.
+
+For this to work you will need a release version for each student.
+In your formgrader you will need to create a folder for each student 
+under the release version of an assignment.
+
+Instead of having your notebooks under
+:code:`release/MyAssignment/MyNotebook.ipynb` you will need to create a
+directory for each student as
+:code:`release/MyAssignment/<student_id>/MyNotebook.ipynb`. These notebooks
+can then be personalized.
+
+.. code-block:: python
+
+   # nbgrader_config.py
+
+   from e2xgrader.config import configure_base, configure_exchange
+
+   c = get_config()
+
+   # Register custom preprocessors for autograding and generating assignments
+   configure_base(c)
+
+   # Register custom exchange
+   configure_exchange(c)
+
+   # Activate the personalized outbound
+   c.Exchange.personalized_outbound = True
+
+Personalized Feedback
+---------------------
+
+Similar to the personalized outbound, there is an option for personalized feedback. 
+This makes sure students can only read their feedback directory. 
+
+.. code-block:: python
+
+   # nbgrader_config.py
+
+   from e2xgrader.config import configure_base, configure_exchange
+
+   c = get_config()
+
+   # Register custom preprocessors for autograding and generating assignments
+   configure_base(c)
+
+   # Register custom exchange
+   configure_exchange(c)
+
+   # Activate the personalized feedback
+   c.Exchange.personalized_feedback = True

docs/source/user_docs/exchange/index.rst

@@ -1,106 +1,9 @@
-.. _custom_exchange:
-
 ===============
 Custom Exchange
 ===============
 
-`e2xgrader` comes with an optional custom exchange. The exchange provides personalized directories for each student.
-
-Activating the Exchange
------------------------
-
-To activate the exchange head over to the section about :ref:`configuring e2xgrader <configure_e2xgrader>`.
-
-Personalized Inbound
---------------------
-
-The custom exchange can be configured to use a personalized inbound. 
-If this is activated, each student will have a personalized inbound directory.
-
-Assume you have the course *MyCourse* and the assignment
-*MyAssignment*. In the original nbgrader exchange the student
-will submit to :code:`<exchange_directory>/MyCourse/inbound/`.
-This will be the same for each student and causes a potential security 
-issue. If a student knows the name of the submission of another student,
-they can read their submission.
-
-If the personalized inbound is used, the student will submit to
-:code:`<exchange_directory>/MyCourse/personalized-inbound/<student_id>/`.
-This directory is only readable by the student.
-
-.. code-block:: python
-
-   # nbgrader_config.py
-
-   from e2xgrader.config import configure_base, configure_exchange
-
-   c = get_config()
-
-   # Register custom preprocessors for autograding and generating assignments
-   configure_base(c)
-
-   # Register custom exchange
-   configure_exchange(c)
-
-   # Activate the personalized inbound
-   c.Exchange.personalized_inbound = True
-
-Personalized Outbound
----------------------
-
-If activated, the custom exchange uses a personalized outbound
-directory for each student.
-
-This allows for creating custom versions of an assignment per student.
-Students will fetch from 
-:code:`<exchange_directory>/MyCourse/outbound/MyAssignment/<student_id>/`.
-
-For this to work you will need a release version for each student.
-In your formgrader you will need to create a folder for each student 
-under the release version of an assignment.
-
-Instead of having your notebooks under
-:code:`release/MyAssignment/MyNotebook.ipynb` you will need to create a
-directory for each student as
-:code:`release/MyAssignment/<student_id>/MyNotebook.ipynb`. These notebooks
-can then be personalized.
-
-.. code-block:: python
-
-   # nbgrader_config.py
-
-   from e2xgrader.config import configure_base, configure_exchange
-
-   c = get_config()
-
-   # Register custom preprocessors for autograding and generating assignments
-   configure_base(c)
-
-   # Register custom exchange
-   configure_exchange(c)
-
-   # Activate the personalized outbound
-   c.Exchange.personalized_outbound = True
-
-Personalized Feedback
----------------------
-
-Similar to the personalized outbound, there is an option for personalized feedback. 
-This makes sure students can only read their feedback directory. 
-
-.. code-block:: python
-
-   # nbgrader_config.py
-
-   from e2xgrader.config import configure_base, configure_exchange
-
-   c = get_config()
-
-   # Register custom preprocessors for autograding and generating assignments
-   configure_base(c)
-
-   # Register custom exchange
-   configure_exchange(c)
+.. toctree::
+   :maxdepth: 2
 
-   # Activate the personalized feedback
-   c.Exchange.personalized_feedback = True
+   base_exchange
+   submit

docs/source/user_docs/exchange/submit.rst

@@ -0,0 +1,92 @@
+Custom Submit Exchange
+======================
+
+The custom exchange also comes with a custom submit. This exchange behaves differently
+based on the active `e2xgrader` mode.
+
+Assignment Mode
+---------------
+
+In `student` mode, the submit exchange will only copy over all files to the exchange directory.
+
+
+Exam Mode
+---------
+
+In `student_exam` mode, the submit exchange will hash all files in the assignment directory and store the hashes in a file.
+The default hashing method is sha1. The file containing the hashes is called `SHA1SUM.txt`.
+The contents of the file can be checked in the terminal with the command:
+
+.. code-block:: bash
+
+   sha1sum -c SHA1SUM.txt
+
+Additionally, the exchange will convert all notebooks to html files for students to check their submission.
+The name of the html file is the same as the notebook file with the extension `_hashcode.html`.
+
+A cell is added to the top of the html file with the hashcode and timestamp of the notebook.
+The hashcode displayed is truncated to 12 characters.
+
+.. figure:: img/submitted_html.png
+   :align: center
+
+   Example of the html file generated by the exam exchange.
+
+The message displayed in the cell is customizable. As an example, here is the configuration for a custom message:
+
+.. code-block:: python
+
+   # nbgrader_config.py
+
+   from e2xgrader.config import configure_base, configure_exchange
+
+   c = get_config()
+
+   # Register custom preprocessors for autograding and generating assignments
+   configure_base(c)
+
+   # Register custom exchange
+   configure_exchange(c)
+
+   c.SubmissionExporter.exam_submitted_message = "Ihre Klausur wurde erfolgreich abgegeben."
+   c.SubmissionExporter.your_hashcode_message = "Ihr Hashcode ist:"
+   c.SubmissionExporter.verify_exam_message = "Bitte überprüfen Sie Ihre Klausur unten und loggen Sie sich aus."
+
+The resulting html file will look like this:
+
+.. figure:: img/submitted_html_de.png
+   :align: center
+
+   Example of the html file generated by the exam exchange with a custom message.
+
+Advanced Exam Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The submit exchange can also be configured to use different `HTMLExporter`.
+It is advised to use an exporter that inherits from `e2xgrader.exporters.E2xExporter`, since it makes sure all custom cells are rendered correctly.
+
+This is done via:
+
+.. code-block:: python
+
+   # nbgrader_config.py
+
+   from e2xgrader.config import configure_base, configure_exchange
+
+   c = get_config()
+
+   # Register custom preprocessors for autograding and generating assignments
+   configure_base(c)
+
+   # Register custom exchange
+   configure_exchange(c)
+
+   # Use a custom HTMLExporter
+   c.ExchangeSubmit.submission_exporter_class = "e2xgrader.exporters.SubmissionExporter"
+
+The exporter will be initialized with the `nbgrader_config`` and called with the `hashcode` and `timestamp` as resources:
+
+.. code-block:: python
+
+   exporter = self.submission_exporter_class(config=self.config)
+   exporter.from_notebook_node(nb, resources=dict(hashcode=hashcode, timestamp=timestamp))