docs(uat): update comments for proper doc generation (#393)

uat/custom-components/client-python-paho/README.md

@@ -132,3 +132,18 @@ Python Paho MQTT does not provide the API to set the Subscription ID in SUBSCRIB
 
 3. Unsubscription
 In Python Paho on_unsubscribe() callback does not provide reason codes for MQTTv3, instead zero code will be returned on success.
+
+## Generate documentation
+
+Install pdoc
+
+```cmd
+pip install pdoc3
+```
+
+Run command
+```cmd
+python -m pdoc --html --config show_source_code=False src
+```
+
+Directory "html" with the documentation will be generated.

uat/custom-components/client-python-paho/src/grpc_client_server/grpc_control_server.py

@@ -56,10 +56,9 @@ class GRPCControlServer(mqtt_client_control_pb2_grpc.MqttClientControlServicer):
     def __init__(self, client: GRPCDiscoveryClient, address: str):
         """
         Construct GRPCControlServer
-        Parameters
-        ----------
-        client - GRPCDiscoveryClient object
-        address - local gRPC service address
+        Args:
+            client: GRPCDiscoveryClient object
+            address: local gRPC service address
         """
         self.__logger = GRPCControlServer.logger
         self.__shutdown_reason = ""
@@ -89,9 +88,8 @@ async def start_grpc_server(self):
     async def wait(self, mqtt_lib: MQTTLib):
         """
         Wait until incoming shutdown request
-        Parameters
-        ----------
-        mqtt_lib - MQTT side of the client to handler incoming requests
+        Args:
+            mqtt_lib: MQTT side of the client to handler incoming requests
         """
         self.__mqtt_lib = mqtt_lib
         self.__logger.info("Server awaiting termination")
@@ -115,11 +113,11 @@ async def ShutdownAgent(self, request: ShutdownRequest, context: grpc.aio.Servic
         """
         override
         Handler of ShutdownAgent gRPC call.
-        Parameters
-        ----------
-        request - incoming request
-        context - request context
-        Returns Empty object
+        Args:
+            request: incoming request
+            context: request context
+        Returns:
+            Empty object
         """
         self.__shutdown_reason = request.reason
         self.__logger.info("shutdownAgent: reason %s", self.__shutdown_reason)
@@ -132,11 +130,11 @@ async def CreateMqttConnection(
         """
         override
         Handler of CreateMqttConnection gRPC call.
-        Parameters
-        ----------
-        request - incoming request
-        context - request context
-        Returns MqttConnectReply object
+        Args:
+            request: incoming request
+            context: request context
+        Returns:
+            MqttConnectReply object
         """
         await self.__check_connect_request(request, context)
 
@@ -216,11 +214,11 @@ async def PublishMqtt(self, request: MqttPublishRequest, context: grpc.aio.Servi
         """
         override
         Handler of PublishMqtt gRPC call.
-        Parameters
-        ----------
-        request - incoming request
-        context - request context
-        Returns MqttPublishReply object
+        Args:
+            request: incoming request
+            context: request context
+        Returns:
+            MqttPublishReply object
         """
         if not request.HasField("msg"):
             self.__logger.warning("PublishMqtt: message is missing")
@@ -308,11 +306,11 @@ async def CloseMqttConnection(self, request: MqttCloseRequest, context: grpc.aio
         """
         override
         Handler of CloseMqttConnection gRPC call.
-        Parameters
-        ----------
-        request - incoming request
-        context - request context
-        Returns Empty object
+        Args:
+            request: incoming request
+            context: request context
+        Returns:
+            Empty object
         """
         timeout = request.timeout
         if timeout < TIMEOUT_MIN:
@@ -351,11 +349,11 @@ async def SubscribeMqtt(
         """
         override
         Handler of SubscribeMqtt gRPC call.
-        Parameters
-        ----------
-        request - incoming request
-        context - request context
-        Returns MqttSubscribeReply object
+        Args:
+            request: incoming request
+            context: request context
+        Returns:
+            MqttSubscribeReply object
         """
         timeout = request.timeout
         if timeout < TIMEOUT_MIN:
@@ -440,11 +438,11 @@ async def UnsubscribeMqtt(
         """
         override
         Handler of UnsubscribeMqtt gRPC call.
-        Parameters
-        ----------
-        request - incoming request
-        context - request context
-        Returns MqttSubscribeReply object
+        Args:
+            request: incoming request
+            context: request context
+        Returns:
+            MqttSubscribeReply object
         """
 
         timeout = request.timeout
@@ -485,11 +483,11 @@ async def UnsubscribeMqtt(
     async def __check_connect_request(self, request: MqttConnectRequest, context: grpc.aio.ServicerContext):
         """
         Check that mqtt connect request is correct.
-        Parameters
-        ----------
-        request - incoming request
-        context - request context
-        Returns MqttConnectReply object
+        Args:
+            request: incoming request
+            context: request context
+        Returns:
+            MqttConnectReply object
         """
         if not request.clientId:
             self.__logger.warning("CreateMqttConnection: clientId can't be empty")

uat/custom-components/client-python-paho/src/grpc_client_server/grpc_discovery_client.py

@@ -24,10 +24,9 @@ class GRPCDiscoveryClient:
     def __init__(self, agent_id: str, address: str):
         """
         Construct GRPCDiscoveryClient
-        Parameters
-        ----------
-        agentId - id of agent to identify control channel by gRPC server
-        address - address of gRPC service, including port
+        Args:
+            agentId: id of agent to identify control channel by gRPC server
+            address: address of gRPC service, including port
         """
         self.__logger = GRPCDiscoveryClient.logger
         self.__agent_id = agent_id
@@ -42,10 +41,9 @@ def __init__(self, agent_id: str, address: str):
     def discovery_agent(self, address: str, port: int):
         """
         Discover the agent.
-        Parameters
-        ----------
-        address - host of local gRPC service
-        port of local gRPC service
+        Args:
+            address: host of local gRPC service
+            port: port of local gRPC service
         """
         request = mqtt_client_control_pb2.DiscoveryRequest(agentId=self.__agent_id, address=address, port=port)
 
@@ -58,9 +56,8 @@ def discovery_agent(self, address: str, port: int):
     def register_agent(self) -> str:
         """
         Register the agent.
-        Parameters
-        ----------
-        Returns IP address of client as visible by server
+        Returns:
+            IP address of client as visible by server
         """
         request = mqtt_client_control_pb2.RegisterRequest(agentId=self.__agent_id)
         reply = None
@@ -76,9 +73,8 @@ def register_agent(self) -> str:
     def unregister_agent(self, reason: str):
         """
         Unregister the agent.
-        Parameters
-        ----------
-        reason - reason of unregistering
+        Args:
+            reason: reason of unregistering
         """
         request = mqtt_client_control_pb2.UnregisterRequest(agentId=self.__agent_id, reason=reason)
         try:
@@ -91,10 +87,9 @@ def on_receive_mqtt_message(self, connection_id: int, mqtt_message: Mqtt5Message
         """
         Called when MQTT message is receive my MQTT client
         and deliver information from it to gRPC server.
-        Parameters
-        ----------
-        connection_id - ID of connection, which received the message
-        mqtt_message - received message
+        Args:
+            connection_id: ID of connection, which received the message
+            mqtt_message: received message
         """
         mqtt_connection_id = MqttConnectionId(connectionId=connection_id)
         request = mqtt_client_control_pb2.OnReceiveMessageRequest(
@@ -119,11 +114,10 @@ def on_mqtt_disconnect(self, connection_id: int, disconnect_info: Mqtt5Disconnec
         """
         Called when MQTT connection has been
         disconnected by client or server side.
-        Parameters
-        ----------
-        connection_id - ID of disconnected connection
-        disconnect_info - disconnect information
-        error_string - specific error information
+        Args:
+            connection_id: ID of disconnected connection
+            disconnect_info: disconnect information
+            error_string: specific error information
         """
         mqtt_connection_id = MqttConnectionId(connectionId=connection_id)
         request = mqtt_client_control_pb2.OnMqttDisconnectRequest(

uat/custom-components/client-python-paho/src/grpc_client_server/grpc_lib.py

@@ -22,12 +22,12 @@ def __init__(self):
     async def make_link(self, agent_id: str, hosts: List[str], port: int) -> GRPCLink:
         """
         Creates and returns GRPCLink object.
-        Parameters
-        ----------
-        agent_id - id of agent to identify control channel by server
-        hosts - host names/IPs to connect to testing framework
-        port - TCP port to connect to
-        Returns GRPCLink object
+        Args:
+            agent_id: id of agent to identify control channel by server
+            hosts: host names/IPs to connect to testing framework
+            port: TCP port to connect to
+        Returns:
+            GRPCLink object
         """
         grpc_link = GRPCLink(agent_id, hosts, port)
         await grpc_link.start_server()

uat/custom-components/client-python-paho/src/grpc_client_server/grpc_link.py

@@ -21,10 +21,9 @@ class ClientConnectResult:  # pylint: disable=too-few-public-methods
     def __init__(self, client: GRPCDiscoveryClient, local_ip: str):
         """
         Construct ClientConnectResult
-        Parameters
-        ----------
-        client - Discovery client object
-        local_ip - local client IP address
+        Args:
+            client: Discovery client object
+            local_ip: local client IP address
         """
         self.client = client
         self.local_ip = local_ip
@@ -38,11 +37,10 @@ class GRPCLink:
     def __init__(self, agent_id: str, hosts: List[str], port: int):
         """
         Construct GRPCLink.
-        Parameters
-        ----------
-        agent_id - id of agent to identify control channel by server
-        hosts - host names/IPs to connect to testing framework
-        port - TCP port to connect to
+        Args:
+            agent_id: id of agent to identify control channel by server
+            hosts: host names/IPs to connect to testing framework
+            port: TCP port to connect to
         """
         self.__logger = GRPCLink.logger
 
@@ -66,9 +64,10 @@ async def start_server(self):
     async def handle_requests(self, mqtt_lib: MQTTLib) -> str:
         """
         Handle gRPC requests.
-        Parameters
-        ----------
-        Returns shutdown reason
+        Args:
+            mqtt_lib: MQTTLib object
+        Returns:
+            shutdown reason
         """
         self.__logger.info("Handle gRPC requests")
         await self.__server.wait(mqtt_lib)
@@ -77,9 +76,8 @@ async def handle_requests(self, mqtt_lib: MQTTLib) -> str:
     def shutdown(self, reason: str):
         """
         Unregister MQTT client control in testing framework.
-        Parameters
-        ----------
-        reason - reason of shutdown
+        Args:
+            reason: reason of shutdown
         """
         self.__logger.info("Shutdown gPRC link")
         self.__client.unregister_agent(reason)
@@ -90,21 +88,19 @@ def shutdown(self, reason: str):
     def build_address(host: str, port: int) -> str:
         """
         Build full address from name/IP and port.
-        Parameters
-        ----------
-        host - host name/IP to connect to testing framework
-        port - TCP port to connect to
+        Args:
+            host: host name/IP to connect to testing framework
+            port: TCP port to connect to
         """
         return host + ":" + str(port)
 
     def __make_clients_connection(self, agent_id: str, hosts: List[str], port: int):
         """
         Search for the available host.
-        Parameters
-        ----------
-        agent_id - id of agent to identify control channel by server
-        hosts - host names/IPs to connect to testing framework
-        port - TCP port to connect to
+        Args:
+            agent_id: id of agent to identify control channel by server
+            hosts: host names/IPs to connect to testing framework
+            port: TCP port to connect to
         """
         last_exception = None
         try:

uat/custom-components/client-python-paho/src/main.py

@@ -30,11 +30,10 @@ class Arguments:  # pylint: disable=too-few-public-methods
     def __init__(self, agent_id: str, hosts: List[str], port: int):
         """
         Construct Arguments
-        Parameters
-        ----------
-        agent_id - id of agent to identify control channel by server
-        hosts - host names/IPs to connect to testing framework
-        port - TCP port to connect to
+        Args:
+            agent_id: id of agent to identify control channel by server
+            hosts: host names/IPs to connect to testing framework
+            port: TCP port to connect to
         """
         self.agent_id = agent_id
         self.hosts = hosts
@@ -52,9 +51,8 @@ def __init__(self):
     def parse_args(self) -> Arguments:
         """
         Setup and run.
-        Parameters
-        ----------
-        Returns parsed arguments
+        Returns:
+            parsed arguments
         """
         parser = argparse.ArgumentParser()
         parser.add_argument(
@@ -90,9 +88,8 @@ def parse_args(self) -> Arguments:
     async def do_all(self, temp_files_manager: TempFilesManager):
         """
         Run program.
-        Parameters
-        ----------
-        temp_files_manager - Temp files manager
+        Args:
+            temp_files_manager: Temp files manager
         """
         arguments = self.parse_args()
         grpc_lib = GRPCLib()
@@ -109,7 +106,8 @@ async def do_all(self, temp_files_manager: TempFilesManager):
     async def main(self) -> int:
         """
         Setup and run.
-        Returns response code, which shows the shutdown reason
+        Returns:
+            response code, which shows the shutdown reason
         """
 
         exit_code = 0