From fd13b16ba823bcd7b6f9c7163e7e75585855d33f Mon Sep 17 00:00:00 2001 From: jwansek Date: Thu, 28 Apr 2022 20:11:13 +0100 Subject: Updated readme and docs --- ExampleAssessments/example.yml | 4 +- ExampleSubmission/example.py | 2 +- README.md | 24 ++++++++++++ Smarker/assessments.py | 5 ++- Smarker/smarker.py | 7 +++- docs/source/_static/readme_error.png | Bin 0 -> 42530 bytes docs/source/_static/readme_functionanalysis.png | Bin 0 -> 48916 bytes docs/source/_static/readme_pytest.png | Bin 0 -> 52787 bytes docs/source/_static/readme_runtimeanalysis.png | Bin 0 -> 16063 bytes docs/source/assessmentyaml.rst | 47 ++++++++++++++++++++++++ docs/source/conf.py | 4 +- docs/source/index.rst | 29 +++++++++++++-- docs/source/readme.md | 24 ++++++++++++ 13 files changed, 137 insertions(+), 9 deletions(-) create mode 100644 docs/source/_static/readme_error.png create mode 100644 docs/source/_static/readme_functionanalysis.png create mode 100644 docs/source/_static/readme_pytest.png create mode 100644 docs/source/_static/readme_runtimeanalysis.png create mode 100644 docs/source/assessmentyaml.rst diff --git a/ExampleAssessments/example.yml b/ExampleAssessments/example.yml index c7695d4..154c733 100644 --- a/ExampleAssessments/example.yml +++ b/ExampleAssessments/example.yml @@ -55,4 +55,6 @@ produced_files: - animals.txt dependencies: files: - - ../wsData.txt \ No newline at end of file + - ../wsData.txt + libraries: + - matplotlib \ No newline at end of file diff --git a/ExampleSubmission/example.py b/ExampleSubmission/example.py index d6f7015..af95c24 100644 --- a/ExampleSubmission/example.py +++ b/ExampleSubmission/example.py @@ -76,5 +76,5 @@ def make_multilines(): print("True\n\nFalse") if __name__ == "__main__": - print(hello_world(int(sys.argv[1])) + "\n\nowo" ) + print(hello_world(int(sys.argv[1]))) make_multilines() \ No newline at end of file diff --git a/README.md b/README.md index a9ab9e3..e7f7c9c 120000 --- a/README.md +++ b/README.md @@ -6,3 +6,27 @@ formats. - [Read the documentation](http://smarker.eda.gay/) - [Get the source code](https://github.com/jwansek/Smarker) - [Mirror](https://git.eda.gay/Smarker/files.html) + +### Features + +- Analyse code and get results as pdf, json, yaml, markdown, or plaintext +- Analyse code outputs and check for regexes +- Test functions and methods +- Generate plagarism reports +- Isolate code in a docker container for security + +![Function Analysis](https://smarker.eda.gay/_static/readme_functionanalysis.png) + +Function Analysis + +![Runtime Analysis](https://smarker.eda.gay/_static/readme_runtimeanalysis.png) + +Runtime Analysis + +![File with an exception](https://smarker.eda.gay/_static/readme_error.png) + +File with an exception + +![pytest](https://smarker.eda.gay/_static/pytest_error.png) + +Using pytest diff --git a/Smarker/assessments.py b/Smarker/assessments.py index a6c4df8..4f32353 100644 --- a/Smarker/assessments.py +++ b/Smarker/assessments.py @@ -24,7 +24,7 @@ def generate_plagarism_report(codes): input("%s..." % td) print(pycode_similar.detect(os.listdir(td))) -if __name__ == "__main__": +def getparser(): config = configparser.ConfigParser() config.read(os.path.join(os.path.split(__file__)[0], "smarker.conf")) @@ -81,7 +81,10 @@ if __name__ == "__main__": default = config.get("mysql", option), help = "Optional argument inherited from config file. Read smarker.conf for details." ) + return parser +if __name__ == "__main__": + parser = getparser() args = vars(parser.parse_args()) with database.SmarkerDatabase( diff --git a/Smarker/smarker.py b/Smarker/smarker.py index 8b8527e..39c22e6 100644 --- a/Smarker/smarker.py +++ b/Smarker/smarker.py @@ -73,7 +73,7 @@ def main(**kwargs): # input("\n\n[tempdir: %s] Press any key to close..." % tempdir) -if __name__ == "__main__": +def getparser(): config = configparser.ConfigParser() config.read(os.path.join(os.path.split(__file__)[0], "smarker.conf")) @@ -127,6 +127,11 @@ if __name__ == "__main__": except KeyError: pass + return parser + +if __name__ == "__main__": + parser = getparser() + args = vars(parser.parse_args()) main(**args) \ No newline at end of file diff --git a/docs/source/_static/readme_error.png b/docs/source/_static/readme_error.png new file mode 100644 index 0000000..9d9ac90 Binary files /dev/null and b/docs/source/_static/readme_error.png differ diff --git a/docs/source/_static/readme_functionanalysis.png b/docs/source/_static/readme_functionanalysis.png new file mode 100644 index 0000000..b51a1dd Binary files /dev/null and b/docs/source/_static/readme_functionanalysis.png differ diff --git a/docs/source/_static/readme_pytest.png b/docs/source/_static/readme_pytest.png new file mode 100644 index 0000000..05ae579 Binary files /dev/null and b/docs/source/_static/readme_pytest.png differ diff --git a/docs/source/_static/readme_runtimeanalysis.png b/docs/source/_static/readme_runtimeanalysis.png new file mode 100644 index 0000000..9f1e636 Binary files /dev/null and b/docs/source/_static/readme_runtimeanalysis.png differ diff --git a/docs/source/assessmentyaml.rst b/docs/source/assessmentyaml.rst new file mode 100644 index 0000000..1d4cb14 --- /dev/null +++ b/docs/source/assessmentyaml.rst @@ -0,0 +1,47 @@ +.. _assessmentyaml: + +Assessment configuration yaml +============================= + +A yaml file defines how assessments work. Here's the `example configuration `_ on git: + +.. literalinclude:: ../../ExampleAssessments/example.yml + :linenos: + :language: yaml + +Configuration files must have a name, from which the assessment will be referred to from now often +Pay attention to the use of lists, even if there is only one file or class, it must still be in a list +Tests are put into pytest and must include the name of the module in functions and classes as shown, +for example it's ``example.MyDate()`` not just ``MyDate``. You must use exactly 4 spaces of indentation. + +``run:`` blocks can analyse the output to stdout of a python file, or read any file. Add a +``monitor:`` block to monitor a specific file or omit to analyse stdout. + +``dependencies:`` blocks add required files using ``files:`` and pypi dependencies using ``libraries:``. + +``produced_files`` lists files that are produced by the code. To analyse files they must be in +this list. They will be deleted after the program runs. + +Functions and methods have a number in their arguments. An error will be shown in the report +if not enough arguments are found. + +Assessment configurations are added to the database: + +.. code-block:: bash + + python3 Smarker/assessments.py -c ExampleAssessments/example.yml -e 1 + +The ``-e`` flag is the number of student enrolled and is optional. The assessments in the +database are listed: + +.. code-block:: bash + + python3 Smarker/assessments.py -l yes + +Which returns a string in the yaml format. Assessments can be deleted (will also deleted +associated submissions) + +.. code-block:: bash + + python3 Smarker/assessments.py -rm example + diff --git a/docs/source/conf.py b/docs/source/conf.py index bef233e..5dd644b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -13,6 +13,7 @@ import os import sys sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "Smarker"))) +sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "ExampleAssessments"))) # print(os.listdir(os.path.abspath(os.path.join("..", "..", "Smarker")))) @@ -32,7 +33,8 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon', - "sphinx_mdinclude" + "sphinx_mdinclude", + 'sphinxarg.ext' ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/source/index.rst b/docs/source/index.rst index 4da39e2..e36cc86 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,6 +6,30 @@ Setting up * Set up a MySQL/MariaDB server. The database will be generated automatically. * Add ``smarker.conf`` to the root directory of the code. See :ref:`configfile` for the structure of this file. * Decide how you want to run the program: with or without docker. +* Add an assessment yaml- :ref:`assessmentyaml`. +* Enroll students: ``python3 Smarker/assessments.py -s 123456789,Eden,Attenborough,E.Attenborough@uea.ac.uk`` + +``smarker.py`` usage +******************** + +Now we are ready to make some reports! For which we use the main file ``smarker.py``: + +.. argparse:: + :module: smarker + :func: getparser + :prog: python Smarker/smarker.py + +Please note that the ``-o`` flag is required for rendering to PDFs. + +``assessments.py`` usage +************************ + +``assessments.py`` contains many useful arguments for interacting with the database: + +.. argparse:: + :module: assessments + :func: getparser + :prog: python Smarker/assessments.py .. toctree:: :maxdepth: 2 @@ -20,10 +44,7 @@ Setting up configfile.rst docker.rst - - - - + assessmentyaml.rst Indices and tables ================== diff --git a/docs/source/readme.md b/docs/source/readme.md index a9ab9e3..e7f7c9c 100644 --- a/docs/source/readme.md +++ b/docs/source/readme.md @@ -6,3 +6,27 @@ formats. - [Read the documentation](http://smarker.eda.gay/) - [Get the source code](https://github.com/jwansek/Smarker) - [Mirror](https://git.eda.gay/Smarker/files.html) + +### Features + +- Analyse code and get results as pdf, json, yaml, markdown, or plaintext +- Analyse code outputs and check for regexes +- Test functions and methods +- Generate plagarism reports +- Isolate code in a docker container for security + +![Function Analysis](https://smarker.eda.gay/_static/readme_functionanalysis.png) + +Function Analysis + +![Runtime Analysis](https://smarker.eda.gay/_static/readme_runtimeanalysis.png) + +Runtime Analysis + +![File with an exception](https://smarker.eda.gay/_static/readme_error.png) + +File with an exception + +![pytest](https://smarker.eda.gay/_static/pytest_error.png) + +Using pytest -- cgit v1.2.3