search

exoscale / python-exoscale

Python bindings for the Exoscale APIs
https://exoscale.github.io/python-exoscale/
ISC License
14 stars 7 forks source link

wip(doc): Try to add the attributes of the return objects #54

Closed mlec1 closed 5 months ago

mlec1 commented 6 months ago

Dear Exoscale Team,

The purpose of this MR is to have the different attributes of the returned object of each function in the python documentation directly instead of having only dict and need to go to the openapi documentation to get the aforementioned attributes.

I took part of the code from _create_operation_call which gave me the following string for example with the delete-load-balancer operation (which is what I wanted). 

id (str): Operation ID.

        reason (str): Operation failure reason. Values are ``'busy'``, ``'conflict'``, ``'fault'``, ``'forbidden'``, ``'incorrect'``, ``'interrupted'``, ``'not-found'``, ``'partial'``, ``'unavailable'``, ``'unknown'``, ``'unsupported'``.

        reference (dict): Related resource reference.

        message (str): Operation message.

        state (str): Operation status. Values are ``'failure'``, ``'pending'``, ``'success'``, ``'timeout'``.

However, as you can see on the following picture, the first id (str) is going to the Returns Type (it seems the doc is parsing the string and splitting the string at the first colon)

image

I have some difficulties to understand the Sphinx documentation and that is something I don't know at all. Therefore, I'm asking for your help, if you could help understand where the Returns Type is defined or how is it defined how to display it, is there a way to display all the attribute properly ??

brutasse commented 5 months ago

@mlec1 thanks for giving this a try :) I submitted #56 based on your work, this was mostly about whitespace. Let me know what you think!