From 0441a5607590095619c23567047ed87a17239f40 Mon Sep 17 00:00:00 2001 From: Frederick Yin Date: Mon, 11 Oct 2021 22:41:09 +0800 Subject: Update README.md Installation and usage documentation Contributing --- README.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 117 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index d159f42..64391db 100644 --- a/README.md +++ b/README.md @@ -21,13 +21,114 @@ student. ## Installation & Usage +First of all obviously clone or download the repo. + +For non-SJTU folks who wish to take a look anyway, Leningrade is mirrored on my +self-hosted CGit instance, [CateGit](https://git.fkfd.me/leningrade.git/). + +You need a decently recent version of Python 3 (tested on 3.9.7) and +dependencies listed in `requirements.txt`. To install the dependencies, run +`pip install -r requirements.txt`. + For C and C++, install [ctags](https://github.com/universal-ctags/ctags) for -code quality evaluation. +code quality evaluation. Not tested yet. + +Having obtained the source code, it's time to configure Leningrade. Make a copy +of `config.example.py` called `config.py`, which is where we will write our +configuration. + +Here is a list of configurations you should (or might) care about: + +```python +"""GENERIC""" +HGROUP_NO = 99 +HGROUP_MEMBERS = [ + ("521370910996", "Vladimir Lenin"), + ("521370910997", "Joseph Stalin"), + ("521370910998", "Nikita Khrushchev"), + ("521370910999", "Mikhail Gorbachev"), +] +LANGUAGE = "matlab" +``` + +These are self-explanatory. Note that the names do not need to match anything, +so you can make them whatever you like. + +```python +MANDATORY_FILES = [f"ex{n}.m" for n in [2, 4, 5, 6]] +OPTIONAL_FILES = [f"ex{n}.m" for n in [1, 3]] +``` + +Of course you can do `["ex2.m", "ex4.m", ...]`. Mandatory files are generally +marked "*" on your homework PDF. The rest are optional. + +```python +"""GITEA""" +GITEA_ORG = "ENGR151-21" +GITEA_TOKEN = "" +``` + +`GITEA_ORG` is your organization name. Shown is its value when your repo is at +`https://focs.ji.sjtu.edu.cn/git/ENGR151-21/hgroup-`. + +For `GITEA_TOKEN`, obtain your token here: +FOCS Gitea > Settings > +[Applications](https://focs.ji.sjtu.edu.cn/git/user/settings/applications) > +Generate New Token: fill in Token Name (Leningrade for example), click Generate +Token > copy the hexadecimal string on the top here. + +```python +"""JOJ""" +JOJ_COURSE_ID = "vg151_fall_2021_manuel" +JOJ_SESSION_ID = "" +JOJ_HOMEWORK_ID = "615542bfb3c06a0006f45dd6" # h2 +``` + +Open the JOJ page where you see "Homework 2", "Homework 1" etc. At the end of +its URL you will see your `JOJ_COURSE_ID`. + +`JOJ_SESSION_ID` is a bit tricky. It is a value of JOJ's cookies. When logged +in to JOJ, hit F12 (or whatever triggers DevTools) in your web browser. Switch +to Networks panel. Click on the request with type "document" or "html". See the +request header called "Cookie"? Copy whatever is behind "sid=" here. "sid" is +short for "session id", and this one we got just now is valid for 30 days. This +means you'll have to redo this once every month or so. + +Open the JOJ entry for the homework you are submitting. The URL should look like +`https://joj.sjtu.edu.cn/d/vg151_fall_2021_manuel/homework/615542bfb3c06a0006f45dd6`. +Here, `615542bfb3c06a0006f45dd6` is the `JOJ_HOMEWORK_ID`. + +Finally, we are ready to run Leningrade. + +If you are not sure, run `python leningrade.py --help`. + +``` +usage: leningrade [-h] -n HOMEWORK_NUMBER [-I] [-G] [-J] + +optional arguments: + -h, --help show this help message and exit + -n HOMEWORK_NUMBER, --homework-number HOMEWORK_NUMBER + An integer. For h1, the value should be 1. + -I, --no-individual Do not check individual submissions. + -G, --no-group Do not check group submission. + -J, --no-joj Do not upload group code to JOJ. JOJ may consume a lot of time. Set this flag if your group work has proven to pass JOJ. +``` + +Self-grade your homework as follows. + +``` +$ python leningrade.py -n +``` + +This will clone (or pull, if it already exists) your group's repo, and run tests +against it. If you have made sure your group code has passed JOJ and no further +changes have been made, you can, in your future runs, set flag `-J` to skip that +test. ## Helper Checklist This section is copied from the Helper's README.md, with modifications. It -enumerates what the Helper will grade your work upon. +enumerates what the Helper will grade your work upon, i.e. rubrics. - [x] At least two days before the group deadline, all students should individually complete all the mandatory tasks and push their work to their @@ -57,10 +158,21 @@ enumerates what the Helper will grade your work upon. This is a non-exhaustive list of Leningrade's improvement-worthy aspects. -- Reliable way to obtain list of mandatory/optional files -- Display grades in a human-friendly format +- Display results as a checklist of what needs to be done - More friendly way to specify exercises - Reestablish USSR - Re-enable multiprocessing for JOJ upload (#1) -- Unify criteria of redundant files + +## Contributing + +You may either (a) open an issue or merge request on SJTU GitLab, or (b) send a +[patch](https://git-send-email.io/) to `patch fkfd me`. + +Notes: +1. Please refrain from introducing too many changes to anything in `worker/`. + Ideally, when a patch is applied to the Helper's workers, we should be able + to apply it on ours without trouble. Please do not run a formatter (autopep8, + black, etc.) on them either. The same goes for `util.py`, which was taken + from the Helper. +1. Can someone please, _please_ look into #1? \ No newline at end of file -- cgit v1.2.3