Python documentation improvements

[matt035343]

Using highpy in my project took a long time. Generally, I would say the Python documentation is sub-par. When the library method signatures only contains strings with types and no argument names (except for arg0, arg1, arg2...), it is really difficult to guess what parameters are accepted in the functions and in what order.
The C documentation, on the other hand, was reasonable and helped me a long way. But the C and Python libraries are not 1-to-1, so there was a bit of trial an error.

Improving the Python documentation would help people to adopt the solver. I would say the documentation at least needs to state all methods/functions and their signatures

[jajhall]

The Python interface is WIP, and I know that the Python documentation is incomplete. HiGHS has only had formal documentation since spring 2023 anyway. It also doesn't help that we're not Python programmers.

Could you give me a few examples illustrating how you feel Python programmers would want "all methods/functions and their signatures" to be defined?

[matt035343]

Could you give me a few examples illustrating how you feel Python programmers would want "all methods/functions and their signatures" to be defined?

Basically, you can do what you did for the C library:
https://ergo-code.github.io/HiGHS/dev/interfaces/c/

For each function/method, describe what parameters are accepted (name, type hint, position, default values, short description) and what is returned (type hint, short description)

Example:

addCol(cost: float, lower: float, upper: float, num_new_nz: int, index: int, value: float) -> kHighsStatus

Add a new column (variable) to the model.

Parameters

* cost: The objective coefficient of the column.
* lower: The lower bound of the column.
* upper: The upper bound of the column.
* num_new_nz: The number of non-zeros in the column.
* index: An iterable of length [num_new_nz] with the row indices.
* value: An iterable of length [num_new_nz] with row values.

Returns
A kHighsStatus enum indicating whether the call succeeded.

Example usage:
h = Highs()
h.addCol(cost=1.0, lower=0.0, upper=1000, num_new_nz=1, index=[0,1], value=[10.0, 0.0])

It also doesn't help that we're not Python programmers.

I might be able to find some time to contribute to some Python documentation if needed. Just let me know.

[jajhall]

Thanks. The C documentation is generated automatically from docstrings in the header file, but we can't do the same with Python, I'm sure, as the definition of each function/method is in the C++ bindings file.

I'll see what can be done!