docs: docstrings for parsers (#1924)

Co-authored-by: Yongxuanzhang <44033547+Yongxuanzhang@users.noreply.github.com>

jina/parsers/__init__.py

@@ -5,6 +5,11 @@
 
 
 def set_pea_parser(parser=None):
+    """Set the parser for the Pea
+
+    :param parser: an optional existing parser to build upon
+    :return: the parser
+    """
     if not parser:
         from .base import set_base_parser
         parser = set_base_parser()
@@ -28,6 +33,11 @@ def set_pea_parser(parser=None):
 
 
 def set_pod_parser(parser=None):
+    """Set the parser for the Pod
+
+    :param parser: an optional existing parser to build upon
+    :return: the parser
+    """
     if not parser:
         from .base import set_base_parser
         parser = set_base_parser()
@@ -42,6 +52,11 @@ def set_pod_parser(parser=None):
 
 
 def set_gateway_parser(parser=None):
+    """Set the parser for the gateway arguments
+
+    :param parser: an optional existing parser to build upon
+    :return: the parser
+    """
     if not parser:
         from .base import set_base_parser
         parser = set_base_parser()
@@ -74,6 +89,11 @@ def set_gateway_parser(parser=None):
 
 
 def set_client_cli_parser(parser=None):
+    """Set the parser for the cli client
+
+    :param parser: an optional existing parser to build upon
+    :return: the parser
+    """
     if not parser:
         from .base import set_base_parser
         parser = set_base_parser()
@@ -89,6 +109,10 @@ def set_client_cli_parser(parser=None):
 
 
 def get_main_parser():
+    """The main parser for Jina
+
+    :return: the parser
+    """
     from .base import set_base_parser
     from .helloworld import set_hw_parser, set_hw_chatbot_parser
     from .helper import _chf, _SHOW_ALL_ARGS

jina/parsers/base.py

@@ -1,9 +1,14 @@
+"""Module containing the base parser for arguments of Jina."""
 import argparse
 
 from .helper import _chf
 
 
 def set_base_parser():
+    """Set the base parser
+
+    :return: the parser
+    """
     from .. import __version__
     from ..helper import colored, get_full_version, format_full_version_info
     # create the top-level parser

jina/parsers/check.py

@@ -1,7 +1,13 @@
+"""Argparser module for the check functions"""
 from .base import set_base_parser
 
 
 def set_check_parser(parser=None):
+    """Set the `check` parser
+
+    :param parser: an optional existing parser to build upon
+    :return: parser
+    """
     if not parser:
         parser = set_base_parser()
 

jina/parsers/client.py

@@ -1,8 +1,13 @@
+"""Module for argparse for Client"""
 from .helper import add_arg_group
 from ..enums import RequestType
 
 
 def mixin_client_cli_parser(parser):
+    """Add the arguments for the client to the parser
+
+    :param parser: the parser configure
+    """
     gp = add_arg_group(parser, title='Client')
 
     gp.add_argument('--request-size', type=int, default=100,

jina/parsers/export_api.py

@@ -1,7 +1,13 @@
+"""Argparser module for the export API"""
 from .base import set_base_parser
 
 
 def set_export_api_parser(parser=None):
+    """Set the parser for the API export
+
+    :param parser: an optional existing parser to build upon
+    :return: the parser
+    """
     if not parser:
         parser = set_base_parser()
 

jina/parsers/flow.py

@@ -1,3 +1,4 @@
+"""Argparser module for Flow"""
 import argparse
 
 from .base import set_base_parser
@@ -7,6 +8,11 @@
 
 
 def set_flow_parser(parser=None):
+    """Set the parser for the flow
+
+    :param parser: an (optional) initial parser to build upon
+    :return: the parser
+    """
     if not parser:
         parser = set_base_parser()
 

jina/parsers/helloworld.py

@@ -1,3 +1,4 @@
+"""Module for hello world argparser"""
 import argparse
 
 from pkg_resources import resource_filename
@@ -8,6 +9,10 @@
 
 
 def mixin_hw_base_parser(parser):
+    """Add the arguments for hello world to the parser
+
+    :param parser: the parser configure
+    """
     gp = add_arg_group(parser, title='General')
     gp.add_argument('--workdir', type=str, default=random_identity(),
                     help='The workdir for hello-world demo'
@@ -17,6 +22,11 @@ def mixin_hw_base_parser(parser):
 
 
 def set_hw_parser(parser=None):
+    """Set the hello world parser
+
+    :param parser: the parser configure
+    :return: the new parser
+    """
     if not parser:
         parser = set_base_parser()
 
@@ -65,6 +75,11 @@ def set_hw_parser(parser=None):
 
 
 def set_hw_chatbot_parser(parser=None):
+    """Set the parser for the hello world chatbot
+
+    :param parser: the parser configure
+    :return: the new parser
+    """
     if not parser:
         parser = set_base_parser()
 

jina/parsers/helper.py

@@ -1,6 +1,8 @@
+"""Module for helper functions in the parser"""
 import argparse
 import os
 import uuid
+from typing import Tuple
 
 _SHOW_ALL_ARGS = 'JINA_FULL_CLI' in os.environ
 if _SHOW_ALL_ARGS:
@@ -9,23 +11,41 @@
 
 
 def add_arg_group(parser, title):
+    """Add the arguments for a specific group to the parser
+
+    :param parser: the parser configure
+    :param title: the group name
+    :return: the new parser
+    """
     return parser.add_argument_group(f'{title} arguments')
 
 
-def UUIDString(astring):
-    """argparse type to check if a string is a valid UUID string"""
+def UUIDString(astring) -> str:
+    """argparse type to check if a string is a valid UUID string
+
+    :param astring: the string to check
+    :return: the string
+    """
     uuid.UUID(astring)
     return astring
 
 
 class KVAppendAction(argparse.Action):
-    """
-    argparse action to split an argument into KEY=VALUE form
+    """argparse action to split an argument into KEY=VALUE form
     on the first = and append to a dictionary.
     This is used for setting up --env
     """
 
     def __call__(self, parser, args, values, option_string=None):
+        """
+        call the KVAppendAction
+
+        # noqa: DAR401
+        :param parser: the parser
+        :param args: args to initialize the values
+        :param values: the values to add to the parser
+        :param option_string: inherited, not used
+        """
         import json
         d = getattr(args, self.dest) or {}
         for value in values:
@@ -41,13 +61,21 @@ def __call__(self, parser, args, values, option_string=None):
 
 
 class DockerKwargsAppendAction(argparse.Action):
-    """
-    argparse action to split an argument into KEY: VALUE form
+    """argparse action to split an argument into KEY: VALUE form
     on the first : and append to a dictionary.
     This is used for setting up arbitrary kwargs for docker sdk
     """
 
     def __call__(self, parser, args, values, option_string=None):
+        """
+        call the DockerKwargsAppendAction
+
+        # noqa: DAR401
+        :param parser: the parser
+        :param args: args to initialize the values
+        :param values: the values to add to the parser
+        :param option_string: inherited, not used
+        """
         import json
         d = getattr(args, self.dest) or {}
 
@@ -179,8 +207,12 @@ def _fill_text(self, text, width, indent):
         lines = self._para_reformat(text, width)
         return '\n'.join(lines)
 
-    def _indents(self, line):
-        """Return line indent level and "sub_indent" for bullet list text."""
+    def _indents(self, line) -> Tuple[int, int]:
+        """Return line indent level and "sub_indent" for bullet list text.
+
+        :param line: the line to check
+        :return: indentation of line and indentation of sub-items
+        """
         import re
         indent = len(re.match(r'( *)', line).group(1))
         list_match = re.match(r'( *)(([*\-+>]+|\w+\)|\w+\.) +)', line)
@@ -192,7 +224,11 @@ def _indents(self, line):
         return (indent, sub_indent)
 
     def _split_paragraphs(self, text):
-        """Split text in to paragraphs of like-indented lines."""
+        """Split text into paragraphs of like-indented lines.
+
+        :param text: the text input
+        :return: list of paragraphs
+        """
 
         import textwrap, re
 
@@ -218,7 +254,12 @@ def _split_paragraphs(self, text):
         return paragraphs
 
     def _para_reformat(self, text, width):
-        """Reformat text, by paragraph."""
+        """Format text, by paragraph.
+
+        :param text: the text to format
+        :param width: the width to apply
+        :return: the new text
+        """
 
         import textwrap
 

jina/parsers/hub/__init__.py

@@ -3,6 +3,11 @@
 
 
 def set_hub_pushpull_parser(parser=None):
+    """Set the parser for the hub push or hub pull
+
+    :param parser: an optional existing parser to build upon
+    :return: the parser
+    """
     if not parser:
         parser = set_base_parser()
 
@@ -15,6 +20,11 @@ def set_hub_pushpull_parser(parser=None):
 
 
 def set_hub_build_parser(parser=None):
+    """Set the parser for `hub build`
+
+    :param parser: the parser configure
+    :return: the new parser
+    """
     if not parser:
         parser = set_base_parser()
 
@@ -28,6 +38,11 @@ def set_hub_build_parser(parser=None):
 
 
 def set_hub_list_parser(parser=None):
+    """Set the parser for `hub list`
+
+    :param parser: the parser configure
+    :return: the new parser
+    """
     if not parser:
         parser = set_base_parser()
 
@@ -38,6 +53,11 @@ def set_hub_list_parser(parser=None):
 
 
 def set_hub_new_parser(parser=None):
+    """Set the parser for the `hub new` command
+
+    :param parser: the parser configure
+    :return: the new parser
+    """
     if not parser:
         parser = set_base_parser()
 
@@ -48,6 +68,10 @@ def set_hub_new_parser(parser=None):
 
 
 def set_hub_parser(parser=None):
+    """Set the parser for the hub
+
+    :param parser: the parser configure
+    """
     if not parser:
         parser = set_base_parser()
 

jina/parsers/hub/build.py

@@ -1,8 +1,13 @@
+"""Argparser module for hub build"""
 from ..helper import add_arg_group
 from ...enums import BuildTestLevel
 
 
 def mixin_hub_build_parser(parser):
+    """Add the arguments for hub build to the parser
+
+    :param parser: the parser configure
+    """
     gp = add_arg_group(parser, title='Build')
     gp.add_argument('path', type=str, help='path to the directory containing '
                                            'Dockerfile, manifest.yml, README.md '

jina/parsers/hub/list.py

@@ -1,7 +1,12 @@
+"""Argparser module for hub list"""
 from ..helper import add_arg_group
 
 
 def mixin_hub_list_parser(parser):
+    """Add the arguments for hub list to the parser
+
+    :param parser: the parser configure
+    """
     gp = add_arg_group(parser, title='List')
     gp.add_argument('--name', type=str,
                     help='The name of hub image')

jina/parsers/hub/login.py

@@ -1,9 +1,14 @@
+"""Argparser module for hub login"""
 import os
 
 from ..helper import add_arg_group
 
 
 def mixin_hub_docker_login_parser(parser):
+    """Add the options for the docker login
+
+    :param parser: the parser
+    """
     gp = add_arg_group(parser, title='Docker login')
 
     gp.add_argument('--username', type=str, help='The Docker registry username',