diff --git a/docs/cli_reference.rst b/docs/cli_reference.rst new file mode 100644 index 0000000..4dc9ce5 --- /dev/null +++ b/docs/cli_reference.rst @@ -0,0 +1,93 @@ +Command-Line Interface +====================== + +PyBryt includes a small command-line interface for performing quick tasks using its functionality. +The main tasks that the CLI currently supports are: + +- compiling reference implementations and saving them to a file +- executing student implementations and saving them to a file +- checking reference implementations against student implementations (as notebooks or pickled objects) + and saving/echoing the results + +Each of the commands is detailed in the :ref:`refererence` below, but a short summary +of each is provided here. The CLI can be invoked via the command ``pybryt`` or by calling PyBryt as a +Python module: ``python3 -m pybryt``. For simplicity, the convention of the former is used here. + + +CLI Sub-commands +---------------- + + +``check`` ++++++++++ + +``pybryt check`` is used to check a student implementation against a reference implementation. It +takes two position arguments corresponding to the path to a reference implementation and the path to +a student implementation. Both paths can lead either to notebooks (which will be executed/compiled +if provided) or to pickle files. + +The output of this command comes in three forms: + +- a pickled :py:class:`ReferenceResult` object, written to a file +- a JSON file with a text-based representation of the ``ReferenceResult`` object +- a report echoed to the console + +To set the output type, use the ``-t`` flag. If a file is written, use the ``-o`` flag to set the +output path (defaults to ``{stu.stem}_results.[pkl|json]``). + +.. code-block:: console + + $ ls + reference.ipynb subm.ipynb + $ pybryt check reference.ipynb subm.ipynb + $ ls + reference.ipynb subm.ipynb subm_results.pkl + $ pybryt check reference.pkl subm.pkl -t json + $ ls + reference.ipynb subm.ipynb subm_results.json subm_results.pkl + $ pybryt check reference.ipynb subm.pkl -t report + REFERENCE: median + SATISFIED: True + MESSAGES: + ... + + +``compile`` ++++++++++++ + +``pybryt compile`` is used to compile a reference implementation to a file. It takes a single positional +argument, the path to the notebook to be compiled. To set the destination path, use the ``-d`` flag. +If a name is needed for the reference implementation, it can be provided with the ``-n`` flag. + +.. code-block:: console + + $ pybryt compile reference.ipynb + $ pybryt compile reference.ipynb -d ref.pkl -n foo + + +``execute`` ++++++++++++ + +``pybryte execute`` is used to execute one or more student implementations and write the memory +footprints to files for futher processing. All paths passed as position arguments to this command +are paths to student implementation notebooks. + +Because execution can be time-consuming, ``pybryt execute`` supports parallelism using Python's +``multiprocessing`` library. To enable parallelism, use the ``-p`` flag. + +.. code-block:: console + + $ pybryt execute submissions/*.ipynb + $ pybryt execute submissions/*.ipynb -p + + +.. _cli_reference: + +Reference +--------- + +This section is a short reference for all of the commands and options for PyBryt's CLI. + +.. click:: pybryt.cli:click_cli + :prog: pybryt + :nested: full diff --git a/docs/conf.py b/docs/conf.py index 714b46a..35e25ca 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,6 +33,7 @@ extensions = [ 'sphinxarg.ext', 'IPython.sphinxext.ipython_console_highlighting', 'IPython.sphinxext.ipython_directive', + 'sphinx_click', ] # extension configurations diff --git a/docs/index.rst b/docs/index.rst index 0c16ab0..999680e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ PyBryt Documentation annotations/index reference_implementations student_implementations + cli_reference api_reference Changelog @@ -31,7 +32,8 @@ benefits are: - Educators do not have to enforce the structure of the solution - Learners practice algorithm design, code design, and solution implementation -- Learners receive quick and meaningful pedagogical feedback, which substantially contributes to the learning experience +- Learners receive quick and meaningful pedagogical feedback, which substantially contributes + to the learning experience - Complexity of the learner's solution can be analyzed - Plagiarism detection and support for reference implementations - Easy integration into existing organizational or institutional grading infrastructure diff --git a/docs/requirements.txt b/docs/requirements.txt index 544a0a5..26dd287 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ furo sphinxcontrib-apidoc sphinx-argparse +sphinx-click diff --git a/pybryt/cli.py b/pybryt/cli.py index 7efd46e..3750243 100644 --- a/pybryt/cli.py +++ b/pybryt/cli.py @@ -67,6 +67,9 @@ def check(ref, stu, name, output_nb, output, output_type): except: raise RuntimeError(f"Could not load the reference implementation {ref}") + if output is None: + output = get_stem(stu) + "_results" + (".pkl", ".json")[output_type == "json"] + if os.path.splitext(stu)[1] == ".ipynb": stu = StudentImplementation(stu, output=output_nb) else: @@ -80,8 +83,6 @@ def check(ref, stu, name, output_nb, output, output_type): if output_type == "pickle": res.dump(output) elif output_type == "json": - if output is None: - output = os.path.splitext(res._default_dump_dest)[0] + ".json" d = res.to_dict() with open(output, "w+") as f: json.dump(d, f, indent=2)