Please document the Python API

[ANogin]

In addition to #24 and #158, it would be very helpful to have a documentation for the Python API, including in docstrings (so that it's readily pulled up in IDEs). I just started writing my first quick test to try out rtamt, and already scratching my head about:

• What are the options for the var type in declare_var? All your examples seem to have "float", but can it be "int" or "bool"? Had to do a grep - and found that rtamt/examples/journal seems to have int?
• What is the format of the spec.update arguments? Examples show a bunch of different usages - I kind of get it, but it would be good to know for sure. Same for the format of the returned result.

[ANogin]

Just to give you an idea of what a novice user might face, here is what my terminal currently looks like :) :

    rob = spec.update(time, (var, val))
...
  File "/Users/aleksey/python-venv/3.12/lib/python3.12/site-packages/rtamt/semantics/dense_time_interpreter.py", line 20, in set_variable_to_ast_from_dataset
    var_name = data[0]
               ~~~~^^^
TypeError: 'int' object is not subscriptable

    rob = spec.update([var, [time, val]])
...
  File "/Users/aleksey/python-venv/3.12/lib/python3.12/site-packages/rtamt/semantics/stl/dense_time/online/once_timed_operation.py", line 27, in update
    self.residual_start = sample[len(sample) - 1][0] + begin
                          ~~~~~~~~~~~~~~~~~~~~~~~^^^
TypeError: 'int' object is not subscriptable

    rob = spec.update([var, [[time, val]]])
...
  File "/Users/aleksey/python-venv/3.12/lib/python3.12/site-packages/rtamt/semantics/stl/dense_time/online/once_timed_operation.py", line 36, in update
    while len(sample) >= i:
          ^^^^^^^^^^^
TypeError: object of type 'int' has no len()

    rob = spec.update(time, [(var, val)])
...
  File "/Users/aleksey/python-venv/3.12/lib/python3.12/site-packages/rtamt/semantics/dense_time_interpreter.py", line 20, in set_variable_to_ast_from_dataset
    var_name = data[0]
               ~~~~^^^
TypeError: 'int' object is not subscriptable

    rob = spec.update([var, [(time, val)]])
...
  File "/Users/aleksey/python-venv/3.12/lib/python3.12/site-packages/rtamt/semantics/stl/dense_time/online/once_timed_operation.py", line 36, in update
    while len(sample) >= i:
          ^^^^^^^^^^^
TypeError: object of type 'int' has no len()

Would have loved to just have spec.update_one(var, time, val) or some such at this point...

[nickovic]

Thanks for the valuable input. We will update the API documentation accordingly and consider extending it with the function that you propose.