From 2b6fe45b4237447df709273e71c84c84798840a6 Mon Sep 17 00:00:00 2001 From: vangef Date: Fri, 3 Mar 2023 13:11:17 +0000 Subject: [PATCH] READMEs update --- BB_gradebooks/README.md | 3 ++- BB_submissions/README.md | 15 ++++++++++----- README.md | 20 ++++++++++---------- 3 files changed, 22 insertions(+), 16 deletions(-) diff --git a/BB_gradebooks/README.md b/BB_gradebooks/README.md index 2a8d258..b7fda4c 100644 --- a/BB_gradebooks/README.md +++ b/BB_gradebooks/README.md @@ -1,6 +1,7 @@ # BBGradebookOrganiser + Blackboard Gradebook Organiser -### Blackboard gradebooks directory: *BB_gradebooks* +## Blackboard gradebooks directory: *BB_gradebooks* Create a directory with an appropriate name for the gradebook / assignment in this directory, and extract the downloaded gradebook .zip file in it. diff --git a/BB_submissions/README.md b/BB_submissions/README.md index d08a67b..96a36de 100644 --- a/BB_submissions/README.md +++ b/BB_submissions/README.md @@ -1,9 +1,14 @@ # BBGradebookOrganiser + Blackboard Gradebook Organiser -### Blackboard submissions directory: *BB_submissions* +## Blackboard submissions directory: *BB_submissions* -- Gradebooks from directory *BB_gradebooks* will be organised into this directory, in a subdirectory with the same name - - e.g. gradebook directory *AssignmentX* in *BB_gradebooks* will be organised into directory *AssignmentX* in *BB_submissions* -- Also, a text file with all submission comments will be created in this directory, with the gradebook name as prefix - - e.g. *AssignmentX_comments.txt* will be created for gradebook *AssignmentX* \ No newline at end of file +Gradebooks will be organised into this directory, in a subdirectory with the same name + +- Gradebook directory *AssignmentX* in *BB_gradebooks* will be organised into directory *AssignmentX* in *BB_submissions* + +Also, a text file with all submission comments will be created in this directory, with the gradebook name as prefix + +- e.g. *AssignmentX_comments.txt* will be created for gradebook *AssignmentX* + \ No newline at end of file diff --git a/README.md b/README.md index d374c61..18fe6f7 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ Blackboard Gradebook Organiser ## Description -**Blackboard Gradebook Organiser** is a tool for organising a downloaded gradebook with assignment submissions from [Blackboard Learn](https://en.wikipedia.org/wiki/Blackboard_Learn). +**Blackboard Gradebook Organiser** is a tool for organising a downloaded gradebook with assignment submissions from [Blackboard Learn ⧉](https://en.wikipedia.org/wiki/Blackboard_Learn). The submission files are organised per student, by extracting the student number from the submission file names and creating a directory per student. Any compressed files (.zip, .rar, .7z) are extracted into the student's directory, with any remaining files submitted individually also moved into the student's directory. Student comments from submissions are also extracted into a single text file for convenient access and review. -Additionally, after organising submissions, you can inspect all submitted files to detect duplicated files from different submissions/students by generating and comparing SHA256 hashes. See section [Inspect submissions](#inspect-submissions-mag) for details. +Optionally, after organising a gradebook, you can inspect submissions to detect duplicated files from different submissions/students by generating and comparing SHA256 hashes. See section [Inspect submissions](#inspect-submissions-mag) for details. ### Features @@ -18,7 +18,7 @@ Additionally, after organising submissions, you can inspect all submitted files - Checks and extracts any comments from the student submission generated text files - Checks if any compressed files (from the contents of the submitted compressed files) have been extracted and organised per student - The path of any extracted and organised compressed files will be displayed on the terminal - they need to be extracted manually -- [Inspect submissions](#inspect-submissions-mag) by SHA256 hash :new: +- [Inspect submissions](#inspect-submissions-mag) by generating and comparing SHA256 hashes of submitted files :new: ## Instructions @@ -36,7 +36,7 @@ Additionally, after organising submissions, you can inspect all submitted files ### Run script -- Before running the script for the first time, install the required packages +- Before running the script for the first time, install the required packages - `python -m pip install -r requirements.txt` - If running on Linux/Mac, you also need to have *unrar* installed in order to be able to extract .rar files - `sudo apt install unrar` for Linux @@ -60,10 +60,10 @@ Additionally, after organising submissions, you can inspect all submitted files ### Information - Generates SHA256 hashes for each submitted file, and outputs list to CSV file - - Can exclude files from hashing, if provided with a CSV file listing the file names + - Can exclude files from hashing, if provided with a CSV file listing the file names - Compares the generated hashes and finds any duplicate hashes - ignores duplicates if they are by the same student/submission - Finds all files with a duplicated hash and outputs them to CSV file with the following information: Student ID, file path, file name (without path), SHA256 hash - - Further inspection and filtering needs to be done manually, depending on the submission files + - Further inspection and filtering needs to be done manually ### Usage @@ -71,13 +71,13 @@ Additionally, after organising submissions, you can inspect all submitted files - `python -m pip install pandas` - Usage: `python inspect_submissions.py GRADEBOOK_DIR_NAME` - Note: run **after** organising a gradebook with `organise_gradebook.py` -- In order to exclude files from hashing, create a CSV file in directory *csv* to provide the file names to be excluded +- (Optional) In order to exclude files from hashing, create a CSV file in directory *csv* to provide the file names to be excluded - e.g. for AssignmentX: create *AssignmentX_excluded.csv*, with a column named "exclude_filename" and list the file names - - Note: the directory *csv* is automatically created when you run `inspect_submissions.py` - you need to create it manually if you want to exclude files before the first run + - Note: the directory *csv* is automatically created when you run `inspect_submissions.py` - you need to create it manually if you want to exclude files before the first run - Generated CSV files can be found in directory *csv*, with *GRADEBOOK_DIR_NAME* as file name prefix - e.g. inspecting submissions for *AssignmentX* will create 2 csv files: - - AssignmentX_file_hashes_[datetime].csv - - AssignmentX_suspicious_[datetime].csv + - *AssignmentX_file_hashes_[datetime].csv* - all files and their hashes + - *AssignmentX_suspicious_[datetime].csv* - files with duplicate hashes ## Notes