User functions guide

[pseusys]

Description

Adds userguide describing user-defined functions of the framework.

Checklist

• I have covered the code with tests
• I have added comments to my code to help others understand it
• I have updated the documentation to reflect the changes
• I have performed a self-review of the changes

[RLKRo]

Add links to examples of usage (if such examples exist in our codebase).

If I understood correctly, information about exception handling is going to be in a separate section. In that case we should move all the specific function information into subsections:

User functions guide
--------------------

Overview
~~~~~~~~

Functions
~~~~~~~~~

``Actor`` handlers
==================

...

Exception Handling
~~~~~~~~~~~~~~~~~~

I think we should also sort the functions in the order of their usage frequency.

[pseusys]

WARNING: the guide has one TODO left, regarding some information that has not been documented yet.

[pseusys]

There is still one TODO left!

[RLKRo]

Maybe split into sections
Overview;
Actor handlers;
Script functions (Pre-transition processors, Pre-response processors, Script conditions and condition handlers, Labels, Responses);
Service functions (Extra handlers, Service handlers, Service conditions, Statistics extractors)?

And also reorder sections (service handlers should be before extra handlers; actor handlers should be last).

I think that Pre-transition and Pre-response could be merged into one section since there is no difference between the two besides the point of execution.

And the guide should include information about the most common use cases for functions with examples (e.g. pre-response processors are commonly used to modify response which is done by updating the response attribute of ctx.current_node).
There should also be links to tutorials that use these functions.

[RLKRo]

There is still one TODO left!

Is this about this line?

They are provided in script dictionary (TODO: parser?) in form of Python functions.

I don't understand why that is needed here. Parser is not merged yet and I don't see the connection between the two.

[pseusys]

There is still one TODO left!

Is this about this line?

They are provided in script dictionary (TODO: parser?) in form of Python functions.

I don't understand why that is needed here. Parser is not merged yet and I don't see the connection between the two.

Some of the functions can only be defined in python diction. AFAIK parser adds support for parsing the dictionary from YAML file. How will the functions (e.g. labels) be represented in the file?

[ruthenian8]

Should we assume that the API update will be merged before this PR or after it? If yes, the processing signature will be different: functions will return None

[pseusys]

I consider API compatible with the current one.