docs: layout / structure changes

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)

docs/instructions/usage.md

@@ -0,0 +1,57 @@
+# **Using BBGradebookOrganiser**
+
+## **Download gradebook**
+
+1. Go to the course page on Blackboard
+
+2. Go to *Grade Centre -> Full Grade Centre*
+
+3. Find the assignment and click on the arrow for more options, and select *Assignment File Download*
+
+4. Select all (click *Show All* at the bottom first, to display all users) and click submit to generate the gradebook zip file
+
+5. Wait for the generated download link to appear, and click to download
+
+## **Extract gradebook**
+
+Extract the downloaded gradebook in a new directory inside *BB_gradebooks*.
+
+- e.g. for `AssignmentX` extract the gradebook in *BB_gradebooks*/`AssignmentX`
+
+## **Organise gradebook**
+
+To organise the gradebook run **`organise_gradebook.py`** and provide the name of the directory with the *extracted* gradebook (from section *Extract gradebook* above) as an argument.
+
+- e.g. for gradebook `AssignmentX` (in *BB_gradebooks*/`AssignmentX`) run:
+
+```console
+python organise_gradebook.py AssignmentX
+```
+
+While running, the script displays on the terminal information and stats about the gradebook submissions and files.
+
+## **Post-run**
+
+All submission files can be found - organised in directories per student number - in directory *BB_submissions*, under the sub-directory named after the gradebook name provided when running the script.
+
+- e.g. `organise_gradebook.py AssignmentX` creates the directory `AssignmentX` inside *BB_submissions*
+
+Each student directory contains:
+
+- the extracted files from the submitted `.zip`, `.rar`, `.7z`
+  
+- the individually submitted files
+  
+- the text file generated by Blackboard for the submission (which also contains any comments left by the student)
+
+All comments found in the gradebook are extracted in a text file in *BB_submissions*, with the gradebook name as prefix.
+
+- e.g. `AssignmentX_comments.txt` will be created for gradebook `AssignmentX`
+
+Compressed files are deleted after successfully extracting and organising the contents.
+
+- Any invalid/corrupt compressed files are moved into folder `__BAD__` inside the gradebook directory
+
+## **Inspect by hash** :mag:
+
+See [***Inspect by hash***](../inspect/about.md) for more information & details.