Getting started with RoboTA common errors
--------------------------------------------

Once the robota-common-errors package has been installed you can either run the provided report which will output
detected common errors to a HTML page, or you can import the functions and incorporate the outputs into your
own workflow.

Running the report
--------------------

The common-errors report is not intended as the primary method for displaying the detected common errors, but is
provided as a simple example of a possible output.

To run the common errors report, from the common-errors root directory run:

``python robota_common_errors/report.py``

This will produce a report in the **webpages** folder called **common-error-report.html**.

Optional parameters for the script are:

* \-\-config_path - This is the path to the robota config file. The default is **./robota-config.yaml**
* \-\-output - This is the path where the report will be output. The default is **./webpages**
* \-\-start - This is the start date of the report. Artifacts (commits, issues etc.) with a creation date older than this
  will not be considered in the report. The default is **2020-01-01**
* \-\-end - This is the end date of the report, Artifacts newer than this will not be considered in the report.
  The default is **the current date**

Using common errors as a library
----------------------------------

If you want to analyse common errors and use the data in your own scripts, you should use the
:meth:`robota_common_errors.report.identify_common_errors` function. This function takes the path to the robota
config, start and end times as arguments and outputs a list of
:class:`~robota_common_errors.common_errors.CommonError`. These can then be parsed into whatever display format
you want to use.

Adding new common errors
--------------------------

Common errors are described in the **error_definitions.yaml** file. The **marking_function** key in the error
description is the name of the method in the code that will be called to assess the error.
The code that actually assesses the error is located in the **common_error_functions.py** file. Functions
to assess a common error must have the signature
**marking_function_name(data_source: DataServer, common_error: CommonError)** and should populate the CommonError
with the result and return this.