diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index b26fa77..ec8e490 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -10,7 +10,7 @@ Blackboard Gradebook Organiser - main (functional) changes and new features log 2023-03-16 Hyperlinks for file paths and names listed in generated CSV files by *inspect by hash* -2023-03-10 Added *inspect gradebook* and merged with *inspect submission* to make [***inspect by hash***](inspect.md) +2023-03-10 Added *inspect gradebook* and merged with *inspect submission* to make [***inspect by hash***](inspect/about.md) 2023-03-02 Added *exclude files from hashing* diff --git a/docs/README.md b/docs/README.md index b8f442e..07d75dd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,7 +10,7 @@ Blackboard Gradebook Organiser **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. Compressed files are extracted into the student's directory, and any remaining individually submitted files are also moved into the student's directory. Student comments from the submissions are also extracted into a single text file for convenient access and review. -Optionally, you can inspect the submissions for identical files (by generating and comparing SHA256 hashes) and detect if any files have been submitted by multiple students. See [Inspect by hash](inspect.md) for more information. +Optionally, you can inspect the submissions for identical files (by generating and comparing SHA256 hashes) and detect if any files have been submitted by multiple students. See [Inspect by hash](inspect/about.md) for more information. ## **Features** @@ -38,7 +38,7 @@ Optionally, you can inspect the submissions for identical files (by generating a - The path of any extracted and organised compressed files will be displayed on the terminal - they need to be extracted manually -- [Inspect by hash](inspect.md) generates and compares SHA256 hashes of all the submitted files, and detects files that are identical and have been submitted by multiple students. Two ways to inspect: +- [Inspect by hash](inspect/about.md) generates and compares SHA256 hashes of all the submitted files, and detects files that are identical and have been submitted by multiple students. Two ways to inspect: - Inspect gradebook: Before organising a gradebook - for identical files in the files submitted to *Blackboard* @@ -46,11 +46,7 @@ Optionally, you can inspect the submissions for identical files (by generating a ## **Instructions** -See [***Instructions***](instructions.md) for more information & details. - -## **Inspect by hash** :mag: - -See [***Inspect by hash***](inspect.md) for more information & details. +See the documentation for [Setup](instructions/setup.md) and [Usage](instructions/usage.md) instructions, and more information & details about [***Inspect by hash***](inspect/about.md). ## **General notes** diff --git a/docs/inspect/about.md b/docs/inspect/about.md new file mode 100644 index 0000000..3def2e2 --- /dev/null +++ b/docs/inspect/about.md @@ -0,0 +1,29 @@ +# **Inspect by hash** :mag: + +Blackboard Gradebook Organiser - Inspect gradebook & submissions by hash + +## **Description** + +With **Inspect by hash** you can inspect the submissions for identical files (by generating and comparing SHA256 hashes) and detect if any files have been submitted by multiple students. The tool has two variations: + +[*Inspect gradebook*](usage.md#inspect-gradebook): Before organising a gradebook - for identical files in the files submitted to *Blackboard* + +[*Inspect submissions*](usage.md#inspect-submissions): After organising a gradebook - for identical files in the files extracted from any submitted compressed files + +## **Features** + +- Generates SHA256 hashes for each submitted file, and outputs the list to a CSV file + + - Can exclude files from hashing, if provided with a CSV file listing the file names (only applicable for *Inspect submissions*) + +- Compares the generated hashes and finds any duplicates - ignores duplicates if they are by the same student/submission + +- Finds all files with the same hash and outputs the list to a CSV file with the following information: + + - *Inspect gradebook*: `Student ID`, `file name`, `SHA256 hash` + + - *Inspect submissions*: `Student ID`, `file path`, `file name`, `SHA256 hash` + +- File names and paths listed in the generated CSV files have hyperlinks to the actual files for a quick inspection of the file contents (or running the files, if executable) + +*Note:* Further analysis needs to be done manually by inspecting and filtering the generated output, depending on the submission and its files. \ No newline at end of file diff --git a/docs/inspect.md b/docs/inspect/usage.md similarity index 58% rename from docs/inspect.md rename to docs/inspect/usage.md index f5657d8..5dd7a0e 100644 --- a/docs/inspect.md +++ b/docs/inspect/usage.md @@ -1,34 +1,6 @@ -# **Inspect by hash** :mag: +# **Using Inspect by hash** :mag: -Blackboard Gradebook Organiser - Inspect gradebook & submissions by hash - -## **Description** - -With **Inspect by hash** you can inspect the submissions for identical files (by generating and comparing SHA256 hashes) and detect if any files have been submitted by multiple students. The tool has two variations: - -[*Inspect gradebook*](#inspect-gradebook): Before organising a gradebook - for identical files in the files submitted to *Blackboard* - -[*Inspect submissions*](#inspect-submissions): After organising a gradebook - for identical files in the files extracted from any submitted compressed files - -## **Features** - -- Generates SHA256 hashes for each submitted file, and outputs the list to a CSV file - - - Can exclude files from hashing, if provided with a CSV file listing the file names (only applicable for *Inspect submissions*) - -- Compares the generated hashes and finds any duplicates - ignores duplicates if they are by the same student/submission - -- Finds all files with the same hash and outputs the list to a CSV file with the following information: - - - *Inspect gradebook*: `Student ID`, `file name`, `SHA256 hash` - - - *Inspect submissions*: `Student ID`, `file path`, `file name`, `SHA256 hash` - -- File names and paths listed in the generated CSV files have hyperlinks to the actual files for a quick inspection of the file contents (or running the files, if executable) - -*Note:* Further analysis needs to be done manually by inspecting and filtering the generated output, depending on the submission and its files. - -## **Instructions** +## **Requirements** Before running the *inspect* scripts for the first time, you also need to install the *pandas* package: @@ -36,7 +8,7 @@ Before running the *inspect* scripts for the first time, you also need to instal python -m pip install pandas ``` -### **Inspect gradebook** +## **Inspect gradebook** If you haven't already, extract the downloaded from *Blackboard* gradebook in a new directory inside *BB_gradebooks* @@ -56,7 +28,7 @@ Generated CSV files can be found in directory `csv-inspect`, with the inspected - `AssignmentX_gradebook_duplicate_[datetime].csv` - files with duplicate hashes -### **Inspect submissions** +## **Inspect submissions** To inspect *submissions* run **`inspect_submissions.py`** and provide the name of the directory with the *organised* gradebook submissions as an argument. diff --git a/docs/instructions/setup.md b/docs/instructions/setup.md new file mode 100644 index 0000000..8fe85ee --- /dev/null +++ b/docs/instructions/setup.md @@ -0,0 +1,37 @@ +# **Requirements & Settings** + +## **Install requirements** + +Before running the script for the first time, install the required python packages: + +Option 1 - Install `py7z`, `rarfile` + +```console +python -m pip install py7zr rarfile +``` + +Option 2 - Install all packages, including `pandas` which is used in [Inspect by hash](../inspect/about.md), using the requirements file + +```console +python -m pip install -r requirements.txt +``` + +**Note**: If running on Linux/Mac, you also need to have `unrar` installed in order to be able to extract `.rar` files (applies for both options 1 and 2) + +- `sudo apt install unrar` for Linux + +- `brew install rar` for Mac + +## (Optional) **Edit defaults** + +You can change the default settings by editing *utils/settings.py*. The main setting you might want to edit is `IGNORE_DIRS` - the list of names for directories, or files, to ignore when extracting from compressed files. + +Ignored directories by default: + +- `__MACOSX` (macOS system generated files) + +- `.git` (git repo files) + +- `node_modules` (npm) + +- `vendor` (composer / laravel) \ No newline at end of file diff --git a/docs/instructions.md b/docs/instructions/usage.md similarity index 65% rename from docs/instructions.md rename to docs/instructions/usage.md index 99f70a1..dc8c7fa 100644 --- a/docs/instructions.md +++ b/docs/instructions/usage.md @@ -1,40 +1,4 @@ -# **Instructions** - -## **Script requirements** - -Before running the script for the first time, install the required python packages: - -Option 1 - install `py7z`, `rarfile` - -```console -python -m pip install py7zr rarfile -``` - -Option 2 - install all packages, including `pandas` which is used in [Inspect by hash](inspect.md), using the requirements file - -```console -python -m pip install -r requirements.txt -``` - -Note: 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 - -- `brew install rar` for Mac - -## (Optional) **Edit script defaults** - -You can change the default settings by editing *utils/settings.py*. The main setting you might want to edit is `IGNORE_DIRS` - the list of names for directories, or files, to ignore when extracting from compressed files. - -Ignored directories by default: - -- `__MACOSX` (macOS system generated files) - -- `.git` (git repo files) - -- `node_modules` (npm) - -- `vendor` (composer / laravel) +# **Using BBGradebookOrganiser** ## **Download gradebook** @@ -90,4 +54,4 @@ Compressed files are deleted after successfully extracting and organising the co ## **Inspect by hash** :mag: -See [***Inspect by hash***](inspect.md) for more information & details. +See [***Inspect by hash***](../inspect/about.md) for more information & details.