.. _user guides: User guides ----------- Student ^^^^^^^ To run EduLint, use the :ref:`the online instance ` or :ref:`the Thonny plugin `. `Thonny `_ is an integrated development environment for novice programmers that we recommend if you are starting to learn programming. Alternatively, you can :ref:`install and run EduLint locally `, but that can be challenging for if you have never installed software from the command line. If you have troubles setting it up, you can always use one of the other means. If you were asked to use a specific configuration, make sure that the file with your code contains a line like :code:`# edulint: config-file=`. Teacher ^^^^^^^ EduLint can provide basic code quality feedback to your students. You have a large degree of control over which defects get reported by choosing a specific configuration. You can also integrate EduLint into a submission system or host your own instance of the web interface. .. _choosing-configuration: Choosing configuration """""""""""""""""""""" You can either just skip this step and stick with :ref:`the default configuration `, pick another one of :ref:`the packaged configurations ` or :ref:`create your own `. Packaged configurations are easier to use (no need to deliver a custom configuration to the students), but less flexible. Custom configuration is very flexible (there are hundreds of detectors), but can take substantial time to create and needs to be distributed to students separately. If you are unsure where to start, try experimenting with the default configuration first. If you want to create you own configuration, start with the full one and remove detectors from it. Distributing the configuration """""""""""""""""""""""""""""" If you choose a non-default configuration, then you need to setup EduLint to use the correct configuration. The most convenient way is to set the :link_option:`config-file` option in the linted file (:ref:`detailed description here `). Then you need to instruct the students to put the configuration line into the file they create, or if you are already distributing solution templates to the student, you can put the configuration line directly into the solution template like so: .. code:: python # edulint: config-file= # write function returning how many 'a's and 'A's are there in the passed string. def count_a(text): return 0 # implement this The configuration line can be anywhere in the file. More on configuring through in-file comments can be found :ref:`here `. If you integrate EduLint into your submission system, then you can just let students run EduLint through the system and handle setting the correct configuration only on the server side, not bothering students with it. Students use EduLint """""""""""""""""""" There are several ways in which the students themselves can use EduLint, described in section `Student`_. You should recommend the way that aligns best with your integration of EduLint. Running EduLint for evaluation """""""""""""""""""""""""""""" If you use a submission system and it is sufficiently flexible, then we recommend integrating EduLint directly into it. EduLint can either be run on the server side, either as a subprocess, or using its :ref:`package API `). Alternatively, you can setup an `EduLint backend `_ and use its API. On top of the backend, you can host your own `frontend `_ and refer your students to that. Alternatively, you can :ref:`run EduLint locally ` to evaluate students' submissions. You may want to enforce that students implement all of EduLint's feedback generated based on the configuration you selected. For evaluation, we recommend setting the :link_option:`ignore-infile-config-for` to :code:`all`. This way, EduLint will report comments used to suppress Flake8's and Pylint's messages by using :code:`# noqa` and :code:`# pylint: disable=all`. Students will therefore not be able to suppress all reports, there will always be at least the report of these comments. But careful, the student will still be able to change the *number* of reported defects, just not bring it down to zero. The command used for evaluation should look as follows: .. code:: bash python3 -m edulint check -o config-file= -o ignore-infile-config-for=all .. code:: python from edulint import check_code _config, problems = check_code([""], ["config-file=", "ignore-infile-config-for=all"]) It is necessary to specify the config file to use, even if it is already specified in the checked file itself. The :code:`ignore-infile-config-for=all` will ignore even EduLint's configuration. EduLint terminates with a non-zero code if it encountered a defect during the linting process or if there was an error. Researcher ^^^^^^^^^^ EduLint can be used for easily reproducible experiments. A :code:`requirements.txt` specifying package versions and :ref:`EduLint's configuration file `, together with a dataset are enough to reproduce the reported defects. EduLint will automatically use any installed flake8 plugins, even if the plugin is not in EduLint's dependencies. Use of Pylint plugins needs to be set through Pylint's :code:`load-plugins` option. Then, you also need to use a configuration file that enables checks from these plugins.