Use rest format in docstrings (#817)

* Use rest format in docstrings

We have a mix, let's sync on the one used by sphinx.

* Fix

* Fix a few issues

* Minor tweaks

* Fix

Author: therve

.generator/templates/api.mustache

@@ -171,48 +171,49 @@ class {{classname}}(object):
         >>> thread = api.{{operationId}}({{#requiredParams}}{{^defaultValue}}{{paramName}}, {{/defaultValue}}{{/requiredParams}}{{#requiredParams}}{{#defaultValue}}{{paramName}}={{{defaultValue}}}, {{/defaultValue}}{{/requiredParams}}async_req=True)
         >>> result = thread.get()
 {{#requiredParams}}
-{{#-last}}
 
-        Args:
-{{/-last}}
 {{/requiredParams}}
 {{#requiredParams}}
-{{^defaultValue}}
-            {{paramName}} ({{dataType}}):{{#description}} {{{.}}}{{/description}}
+{{^defaultValue}}{{#description}}
+        :param {{paramName}}: {{{.}}}{{/description}}
+        :type {{paramName}}: {{dataType}}
 {{/defaultValue}}
 {{/requiredParams}}
 {{#requiredParams}}
-{{#defaultValue}}
-            {{paramName}} ({{dataType}}):{{#description}} {{{.}}}{{/description}} Defaults to {{{defaultValue}}}. Must be one of [{{{defaultValue}}}]
+{{#defaultValue}}{{#description}}
+        :param {{paramName}}: {{{.}}} Defaults to {{{defaultValue}}}. Must be one of [{{{defaultValue}}}]{{/description}}
+        :type {{paramName}}: {{dataType}}
 {{/defaultValue}}
 {{/requiredParams}}
+    {{#optionalParams}}{{#description}}
+        :param {{paramName}}: {{{.}}}{{#defaultValue}} If omitted the server will use the default value of {{{defaultValue}}}.{{/defaultValue}}{{/description}}
+        :type {{paramName}}: {{dataType}}, optional
+    {{/optionalParams}}
+        :param _return_http_data_only: Response data without head status
+            code and headers. Default is True.
+        :type _return_http_data_only: bool
+        :param _preload_content: If False, the urllib3.HTTPResponse object
+            will be returned without reading/decoding response data.
+            Default is True.
+        :type _preload_content: bool
+        :param _request_timeout: Timeout setting for this request. If one
+            number provided, it will be total request timeout. It can also be a
+            pair (tuple) of (connection, read) timeouts.  Default is None.
+        :type _request_timeout: float/tuple
+        :param _check_input_type: Specifies if type checking should be done one
+            the data sent to the server. Default is True.
+        :type _check_input_type: bool
+        :param _check_return_type: Specifies if type checking should be done
+            one the data received from the server. Default is True.
+        :type _check_return_type: bool
+        :param _host_index: Specifies the index of the server that we want to
+            use. Default is read from the configuration.
+        :type _host_index: int/None
+        :param async_req: Execute request asynchronously.
+        :type async_req: bool
 
-        Keyword Args:{{#optionalParams}}
-            {{paramName}} ({{dataType}}): [optional]{{#description}} {{{.}}}{{/description}}{{#defaultValue}} If omitted the server will use the default value of {{{defaultValue}}}.{{/defaultValue}}{{/optionalParams}}
-            _return_http_data_only (bool): response data without head status
-                code and headers. Default is True.
-            _preload_content (bool): if False, the urllib3.HTTPResponse object
-                will be returned without reading/decoding response data.
-                Default is True.
-            _request_timeout (float/tuple): timeout setting for this request. If one
-                number provided, it will be total request timeout. It can also
-                be a pair (tuple) of (connection, read) timeouts.
-                Default is None.
-            _check_input_type (bool): specifies if type checking
-                should be done one the data sent to the server.
-                Default is True.
-            _check_return_type (bool): specifies if type checking
-                should be done one the data received from the server.
-                Default is True.
-            _host_index (int/None): specifies the index of the server
-                that we want to use.
-                Default is read from the configuration.
-            async_req (bool): execute request asynchronously
-
-        Returns:
-            {{#returnType}}{{returnType}}{{/returnType}}{{^returnType}}None{{/returnType}}
-                If the method is called asynchronously, returns the request
-                thread.
+        :return: If the method is called asynchronously, returns the request thread.
+        :rtype: {{#returnType}}{{returnType}}{{/returnType}}{{^returnType}}None{{/returnType}}
         """
         kwargs = self._{{operationId}}_endpoint.default_arguments(kwargs)
 {{#requiredParams}}

.generator/templates/api_client.mustache

@@ -47,12 +47,12 @@ class ApiClient(object):
     Ref: https://openapi-generator.tech
     Do not edit the class manually.
 
-    :param configuration: .Configuration object for this client
-    :param header_name: a header to pass when making calls to the API.
-    :param header_value: a header value to pass when making calls to
+    :param configuration: Configuration object for this client
+    :param header_name: A header to pass when making calls to the API.
+    :param header_value: A header value to pass when making calls to
         the API.
-    :param cookie: a cookie to include in the header when making calls
-        to the API
+    :param cookie: A cookie to include in the header when making calls
+        to the API.
     :param pool_threads: The number of threads to use for async requests
         to the API. More threads means more concurrent API requests.
     """
@@ -177,10 +177,11 @@ class ApiClient(object):
 {{/tornado}}
 
     def parameters_to_multipart(self, params, collection_types):
-        """Get parameters as list of tuples, formatting as json if value is collection_types
+        """Get parameters as list of tuples, formatting as json if value is collection_types.
+
+        :param params: Parameters as list of two-tuples.
+        :param collection_types: Parameter collection types.
 
-        :param params: Parameters as list of two-tuples
-        :param dict collection_types: Parameter collection types
         :return: Parameters as list of tuple or urllib3.fields.RequestField
         """
         new_params = []
@@ -198,15 +199,15 @@ class ApiClient(object):
 
     @classmethod
     def sanitize_for_serialization(cls, obj):
-        """Prepares data for transmission before it is sent with the rest client
+        """Prepares data for transmission before it is sent with the rest client.
         If obj is None, return None.
         If obj is str, int, long, float, bool, return directly.
-        If obj is datetime.datetime, datetime.date
-            convert to string in iso8601 format.
+        If obj is datetime.datetime, datetime.date convert to string in iso8601 format.
         If obj is list, sanitize each element in the list.
         If obj is dict, return the dict.
         If obj is OpenAPI model, return the properties dict.
-        If obj is io.IOBase, return the bytes
+        If obj is io.IOBase, return the bytes.
+
         :param obj: The data to serialize.
         :return: The serialized form of data.
         """
@@ -616,29 +617,32 @@ class AsyncApiClient(ApiClient):
 class Endpoint(object):
     def __init__(self, settings=None, params_map=None,
                  headers_map=None, api_client=None):
-        """Creates an endpoint
-
-        Args:
-            settings (dict): see below key value pairs
-                'response_type' (tuple/None): response type
-                'auth' (list): a list of auth type keys
-                'endpoint_path' (str): the endpoint path
-                'operation_id' (str): endpoint string identifier
-                'http_method' (str): POST/PUT/PATCH/GET etc
-                'servers' (list): list of str servers that this endpoint is at
-            params_map (dict): see below key value pairs
-                'required' (bool): whether the parameter is required
-                'nullable' (bool): whether the parameter is nullable
-                'validations' (dict): the validations dictionaries
-                'allowed_values' (dict): the allowed values (enum) dictionaries
-                'openapi_types' (dict): param_name to openapi type
-                'attribute' (str): camelCase name
-                'location' (str): 'body', 'file', 'form', 'header', 'path', 'query'
-                'collection_format' (str): `csv` etc.
-            headers_map (dict): see below key value pairs
-                'accept' (list): list of Accept header strings
-                'content_type' (list): list of Content-Type header strings
-            api_client (ApiClient) api client instance
+        """Creates an endpoint.
+
+        :param settings: See below key value pairs:
+            'response_type' (tuple/None): response type
+            'auth' (list): a list of auth type keys
+            'endpoint_path' (str): the endpoint path
+            'operation_id' (str): endpoint string identifier
+            'http_method' (str): POST/PUT/PATCH/GET etc
+            'servers' (list): list of str servers that this endpoint is at
+        :type settings: dict
+        :param params_map: See below key value pairs:
+            'required' (bool): whether the parameter is required
+            'nullable' (bool): whether the parameter is nullable
+            'validations' (dict): the validations dictionaries
+            'allowed_values' (dict): the allowed values (enum) dictionaries
+            'openapi_types' (dict): param_name to openapi type
+            'attribute' (str): camelCase name
+            'location' (str): 'body', 'file', 'form', 'header', 'path', 'query'
+            'collection_format' (str): `csv` etc.
+        :type params_map: dict
+        :param headers_map: See below key value pairs:
+            'accept' (list): list of Accept header strings
+            'content_type' (list): list of Content-Type header strings
+        :type headers_map: dict
+        :param api_client API client instance.
+        :type api_client: ApiClient
         """
         self.settings = settings
         self.params_map = params_map