.. _otter_assign_usage: Usage and Output ================ Otter Assign is called using the ``otter assign`` command. This command takes in two required arguments. The first is ``master``, the path to the master notebook (the one formatted as described above), and the second is ``result``, the path at which output shoud be written. **Otter Assign will automatically recognize the language of the notebook** by looking at the kernel metadata; similarly, if using an Rmd file, it will automatically choose the language as R. This behavior can be overridden using the ``-l`` flag which takes the name of the language as its argument. The default behavior of Otter Assign is to do the following: #. Filter test cells from the master notebook and write these to test files #. Add Otter initialization, export, and ``Notebook.check_all`` cells #. Clear outputs and write questions (with metadata hidden), prompts, and solutions to a notebook in a new ``autograder`` directory #. Write *all* tests to ``autograder/tests`` #. Copy autograder notebook with solutions removed into a new ``student`` directory #. Write *public* tests to ``student/tests`` #. Copy ``files`` into ``autograder`` and ``student`` directories #. Run all tests in ``autograder/tests`` on the solutions notebook to ensure they pass #. (If ``generate`` is passed,) generate a Gradescope autograder zipfile from the ``autograder`` directory The behaviors described in step 2 can be overridden using the optional arguments described in the help specification. **An important note:** make sure that you *run all cells* in the master notebook and save it *with the outputs* so that Otter Assign can generate the test files based on these outputs. The outputs will be cleared in the copies generated by Otter Assign. To run Otter Assign on a v0-formatted notebook, make sure to use the ``--v0`` flag. Python Output Additions ----------------------- The following additional cells are included *only* in Python notebooks. Export Formats and Flags ++++++++++++++++++++++++ By default, Otter Assign adds an initialization cell at the *top* of the notebook with the contents .. code-block:: python # Initialize Otter import otter grader = otter.Notebook() To prevent this behavior, add the `init_cell: false` configuration in your assignment metadata. Otter Assign also automatically adds a check-all cell and an export cell to the end of the notebook. The check-all cells consist of a Markdown cell: .. code-block:: markdown To double-check your work, the cell below will rerun all of the autograder tests. and a code cell that calls ``otter.Notebook.check_all``: .. code-block:: python grader.check_all() The export cells consist of a Markdown cell: .. code-block:: markdown ## Submission Make sure you have run all cells in your notebook in order before running the cell below, so that all images/graphs appear in the output. **Please save before submitting!** and a code cell that calls ``otter.Notebook.export`` with HTML comment filtering: .. code-block:: python # Save your notebook first, then run this cell to export. grader.export("/path/to/notebook.ipynb") These behaviors can be changed with the corresponding assignment metadata configurations. **Note:** Otter Assign currently only supports :ref:`HTML comment filtering `. This means that if you have other cells you want included in the export, you must delimit them using HTML comments, not using cell tags. Otter Assign Example -------------------- Consider the directory stucture below, where ``hw00/hw00.ipynb`` is an Otter Assign-formatted notebook. .. code-block:: hw00 ├── data.csv └── hw00.ipynb To generate the distribution versions of ``hw00.ipynb`` (after changing into the ``hw00`` directory), I would run .. code-block:: otter assign hw00.ipynb dist --v0 If it was an Rmd file instead, I would run .. code-block:: otter assign hw00.Rmd dist --v0 This will create a new folder called ``dist`` with ``autograder`` and ``student`` as subdirectories, as described above. .. code-block:: hw00 ├── data.csv ├── dist │ ├── autograder │ │ ├── hw00.ipynb │ │ └── tests │ │ ├── q1.(py|R) │ │ └── q2.(py|R) # etc. │ └── student │ ├── hw00.ipynb │ └── tests │ ├── q1.(py|R) │ └── q2.(py|R) # etc. └── hw00.ipynb In generating the distribution versions, I can prevent Otter Assign from rerunning the tests using the ``--no-run-tests`` flag: .. code-block:: otter assign --no-run-tests hw00.ipynb dist --v0 Because tests are not run on R notebooks, the above configuration would be ignored if ``hw00.ipynb`` had an R kernel.