py2docfx 0.1.1rc1538122__py3-none-any.whl → 0.1.1rc1634530__py3-none-any.whl

py2docfx/docfx_yaml/build_finished.py

@@ -26,24 +26,161 @@ scientific_notation_regex = re.compile(r'^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)$
 def string_representer(dumper, data):
     return dumper.represent_scalar(u"tag:yaml.org,2002:str", data,
                                    style="'" if (scientific_notation_regex.match(data)) else None)
+
 yml.add_representer(str, string_representer)
 
+def merge_params(arg_params, doc_params):
+    merged_params = deepcopy(doc_params)
+    # merge arg_params into merged_params
+    for arg_param in arg_params:
+        for merged_param in merged_params:
+            if arg_param['id'] == merged_param['id']:
+                if "defaultValue" in arg_param.keys():
+                    merged_param["defaultValue"] = arg_param["defaultValue"]
+                if "type" in arg_param.keys():
+                    merged_param["type"] = arg_param["type"]
+                if "isRequired" in arg_param.keys():
+                    if  arg_param["isRequired"] == False:
+                        merged_param["isRequired"] = arg_param["isRequired"]
+                break
+        else:
+            merged_params.append(arg_param)
+    return merged_params
+
+def remove_params_without_id(params):
+    new_params = []
+    for param in params:
+        if 'id' in param:
+            new_params.append(param)
+    return new_params
+
+def add_isrequired_if_needed(obj, key: str):
+        if key in obj['syntax'] and obj['type'] in ['class', 'function', 'method']:
+            for args in obj['syntax'][key]:
+                if 'isRequired' not in args and 'defaultValue' not in args:
+                    args['isRequired'] = True
+
+def get_merged_params(obj, info_field_data, key: str):
+    merged_params = []
+    arg_params = obj.get('syntax', {}).get(key, [])
+    if key in info_field_data[obj['uid']]:
+        doc_params = info_field_data[obj['uid']].get(
+            key, [])
+        if arg_params and doc_params:
+            if len(arg_params) - len(doc_params) > 0:
+                print("Documented params don't match size of params:"" {}".format(obj['uid']))   # lgtm [py/clear-text-logging-sensitive-data]
+            doc_params = remove_params_without_id(doc_params)
+            merged_params = merge_params(arg_params, doc_params)
+    else:
+        merged_params = arg_params
+
+    return merged_params
+
+def raise_up_fields(obj):
+    # Raise up summary
+    if 'summary' in obj['syntax'] and obj['syntax']['summary']:
+        obj['summary'] = obj['syntax'].pop(
+            'summary').strip(" \n\r\r")
+
+    # Raise up remarks
+    if 'remarks' in obj['syntax'] and obj['syntax']['remarks']:
+        obj['remarks'] = obj['syntax'].pop('remarks')
+
+    # Raise up seealso
+    if 'seealso' in obj['syntax'] and obj['syntax']['seealso']:
+        obj['seealsoContent'] = obj['syntax'].pop('seealso')
+
+    # Raise up example
+    if 'example' in obj['syntax'] and obj['syntax']['example']:
+        obj.setdefault('example', []).append(
+            obj['syntax'].pop('example'))
+
+    # Raise up exceptions
+    if 'exceptions' in obj['syntax'] and obj['syntax']['exceptions']:
+        obj['exceptions'] = obj['syntax'].pop('exceptions')
+
+    # Raise up references
+    if 'references' in obj['syntax'] and obj['syntax']['references']:
+        obj.setdefault('references', []).extend(
+            obj['syntax'].pop('references'))
+
+def merge_data(obj, info_field_data, yaml_data):
+    # Avoid entities with same uid and diff type.
+    # Delete `type` temporarily
+    del(info_field_data[obj['uid']]['type'])
+    if 'syntax' not in obj:
+        obj['syntax'] = {}
+    merged_params = get_merged_params(obj, info_field_data, 'parameters')
+    merged_kwargs = get_merged_params(obj, info_field_data, 'keywordOnlyParameters')
+
+    obj['syntax'].update(info_field_data[obj['uid']])
+
+    # Merging parameters and keywordOnlyParameters is required,
+    # becasue parameters and keywordOnlyParameters can be in both signature and docstring
+    # For positionalOnlyParameters, it's not required, because it's only in signature so far
+    if merged_params:
+        obj['syntax']['parameters'] = merged_params
+    if merged_kwargs:
+        obj['syntax']['keywordOnlyParameters'] = merged_kwargs
+
+    add_isrequired_if_needed(obj, 'parameters')
+    add_isrequired_if_needed(obj, 'keywordOnlyParameters')
+    add_isrequired_if_needed(obj, 'positionalOnlyParameters')
+
+    raise_up_fields(obj)
+
+    # add content of temp list 'added_attribute' to children and yaml_data
+    if 'added_attribute' in obj['syntax'] and obj['syntax']['added_attribute']:
+        added_attribute = obj['syntax'].pop('added_attribute')
+        # TODO: yaml_data is updated wihle iterated. 
+        # `added_attribute` items are copied from class api's `obj` to `yaml_data`
+        # Then iterate again
+        # Should iterate uid and merge yaml_data, added_attribute
+        for attrData in added_attribute:
+            existed_Data = next(
+                (n for n in yaml_data if n['uid'] == attrData['uid']), None)
+            if existed_Data:
+                # Update data for already existed one which has attribute comment in source file
+                existed_Data.update(attrData)
+            else:
+                obj.get('children', []).append(attrData['uid'])
+                yaml_data.append(attrData)
+    # Revert `type` for other objects to use
+    info_field_data[obj['uid']]['type'] = obj['type']
+
+def find_node_in_toc_tree(toc_yaml, to_add_node):
+    for module in toc_yaml:
+        if module['name'] == to_add_node:
+            return module
+
+        if 'items' in module:
+            items = module['items']
+            found_module = find_node_in_toc_tree(items, to_add_node)
+            if found_module != None:
+                return found_module
+
+    return None
+
+def build_nested_toc(toc_yaml, uid):
+    # Build nested TOC
+    if uid.count('.') >= 1:
+        parent_level = '.'.join(uid.split('.')[:-1])
+        found_node = find_node_in_toc_tree(toc_yaml, parent_level)
+
+        if found_node:
+            found_node.pop('uid', 'No uid found')
+            found_node.setdefault('items', [{'name': 'Overview', 'uid': parent_level}]).append(
+                {'name': uid, 'uid': uid})
+        else:
+            toc_yaml.append({'name': uid, 'uid': uid})
+
+    else:
+        toc_yaml.append({'name': uid, 'uid': uid})
+
 def build_finished(app, exception):
     """
     Output YAML on the file system.
     """
-    def find_node_in_toc_tree(toc_yaml, to_add_node):
-        for module in toc_yaml:
-            if module['name'] == to_add_node:
-                return module
-
-            if 'items' in module:
-                items = module['items']
-                found_module = find_node_in_toc_tree(items, to_add_node)
-                if found_module != None:
-                    return found_module
-
-        return None
 
     def convert_class_to_enum_if_needed(obj):
         if (obj.get('inheritance'), None):
@@ -64,37 +201,23 @@ def build_finished(app, exception):
                             app.env.docfx_info_uid_types[obj['uid']] = 'enum'
                             return
 
-    def merge_params(arg_params, doc_params):
-        merged_params = deepcopy(doc_params)
-        # merge arg_params into merged_params
-        for arg_param in arg_params:
-            for merged_param in merged_params:
-                if arg_param['id'] == merged_param['id']:
-                    if "defaultValue" in arg_param.keys():
-                        merged_param["defaultValue"] = arg_param["defaultValue"]
-                    if "type" in arg_param.keys():
-                        merged_param["type"] = arg_param["type"]
-                    if "isRequired" in arg_param.keys():
-                        if  arg_param["isRequired"] == False:
-                            merged_param["isRequired"] = arg_param["isRequired"]
-                    break
-            else:
-                merged_params.append(arg_param)
-        return merged_params
-
-    def remove_params_without_id(params):
-        new_params = []
-        for param in params:
-            if 'id' in param:
-                new_params.append(param)
-        return new_params
-
     normalized_outdir = os.path.normpath(os.path.join(
         app.builder.outdir,  # Output Directory for Builder
         API_ROOT
     ))
+
     ensuredir(normalized_outdir)
 
+    def filter_out_self_from_args(obj):
+        arg_params = obj.get('syntax', {}).get('parameters', [])
+        if(len(arg_params) > 0 and 'id' in arg_params[0]):
+            if (arg_params[0]['id'] == 'self') or (obj['type'] in ['class', 'method'] and arg_params[0]['id'] == 'cls'):
+                # Support having `self` as an arg param, but not documented
+                # Not document 'cls' of constuctors and class methods too
+                arg_params = arg_params[1:]
+                obj['syntax']['parameters'] = arg_params
+        return obj
+
     toc_yaml = []
     # Used to record filenames dumped to avoid confliction
     # caused by Windows case insensitive file system
@@ -103,8 +226,8 @@ def build_finished(app, exception):
     # Order matters here, we need modules before lower level classes,
     # so that we can make sure to inject the TOC properly
     # put app.env.docfx_yaml_packages after app.env.docfx_yaml_modules to keep same TOC items order
-    for data_set in (app.env.docfx_yaml_modules,
-                     app.env.docfx_yaml_packages,
+    for data_set in (app.env.docfx_yaml_packages,
+                     app.env.docfx_yaml_modules,
                      app.env.docfx_yaml_classes,
                      app.env.docfx_yaml_functions):  # noqa
 
@@ -116,86 +239,11 @@ def build_finished(app, exception):
             references = []
             # Merge module data with class data
             for obj in yaml_data:
-                arg_params = obj.get('syntax', {}).get('parameters', [])
-                if(len(arg_params) > 0 and 'id' in arg_params[0]):
-                    if (arg_params[0]['id'] == 'self') or (obj['type'] in ['class', 'method'] and arg_params[0]['id'] == 'cls'):
-                        # Support having `self` as an arg param, but not documented
-                        # Not document 'cls' of constuctors and class methods too
-                        arg_params = arg_params[1:]
-                        obj['syntax']['parameters'] = arg_params
+                obj = filter_out_self_from_args(obj)
+
                 if obj['uid'] in app.env.docfx_info_field_data and \
                         obj['type'] == app.env.docfx_info_field_data[obj['uid']]['type']:
-                    # Avoid entities with same uid and diff type.
-                    # Delete `type` temporarily
-                    del(app.env.docfx_info_field_data[obj['uid']]['type'])
-                    if 'syntax' not in obj:
-                        obj['syntax'] = {}
-                    merged_params = []
-                    if 'parameters' in app.env.docfx_info_field_data[obj['uid']]:
-                        doc_params = app.env.docfx_info_field_data[obj['uid']].get(
-                            'parameters', [])
-                        if arg_params and doc_params:
-                            if len(arg_params) - len(doc_params) > 0:
-                                print("Documented params don't match size of params:"" {}".format(obj['uid']))   # lgtm [py/clear-text-logging-sensitive-data]
-                            doc_params = remove_params_without_id(doc_params)
-                            merged_params = merge_params(arg_params, doc_params)
-
-                    obj['syntax'].update(
-                        app.env.docfx_info_field_data[obj['uid']])
-                    if merged_params:
-                        obj['syntax']['parameters'] = merged_params
-
-                    if 'parameters' in obj['syntax'] and obj['type'] == 'method':
-                        for args in obj['syntax']['parameters']:
-                            if 'isRequired' not in args and 'defaultValue' not in args:
-                                args['isRequired'] = True
-
-                    # Raise up summary
-                    if 'summary' in obj['syntax'] and obj['syntax']['summary']:
-                        obj['summary'] = obj['syntax'].pop(
-                            'summary').strip(" \n\r\r")
-
-                    # Raise up remarks
-                    if 'remarks' in obj['syntax'] and obj['syntax']['remarks']:
-                        obj['remarks'] = obj['syntax'].pop('remarks')
-
-                    # Raise up seealso
-                    if 'seealso' in obj['syntax'] and obj['syntax']['seealso']:
-                        obj['seealsoContent'] = obj['syntax'].pop('seealso')
-
-                    # Raise up example
-                    if 'example' in obj['syntax'] and obj['syntax']['example']:
-                        obj.setdefault('example', []).append(
-                            obj['syntax'].pop('example'))
-
-                    # Raise up exceptions
-                    if 'exceptions' in obj['syntax'] and obj['syntax']['exceptions']:
-                        obj['exceptions'] = obj['syntax'].pop('exceptions')
-
-                    # Raise up references
-                    if 'references' in obj['syntax'] and obj['syntax']['references']:
-                        obj.setdefault('references', []).extend(
-                            obj['syntax'].pop('references'))
-
-                    # add content of temp list 'added_attribute' to children and yaml_data
-                    if 'added_attribute' in obj['syntax'] and obj['syntax']['added_attribute']:
-                        added_attribute = obj['syntax'].pop('added_attribute')
-                        # TODO: yaml_data is updated wihle iterated. 
-                        # `added_attribute` items are copied from class api's `obj` to `yaml_data`
-                        # Then iterate again
-                        # Should iterate uid and merge yaml_data, added_attribute
-                        for attrData in added_attribute:
-                            existed_Data = next(
-                                (n for n in yaml_data if n['uid'] == attrData['uid']), None)
-                            if existed_Data:
-                                # Update data for already existed one which has attribute comment in source file
-                                existed_Data.update(attrData)
-                            else:
-                                obj.get('children', []).append(attrData['uid'])
-                                yaml_data.append(attrData)
-                    # Revert `type` for other objects to use
-                    app.env.docfx_info_field_data[obj['uid']
-                                                  ]['type'] = obj['type']
+                    merge_data(obj, app.env.docfx_info_field_data, yaml_data)
 
                 if 'references' in obj:
                     # Ensure that references have no duplicate ref
@@ -212,20 +260,20 @@ def build_finished(app, exception):
                 if (obj['type'] == 'class' and obj['inheritance']):
                     convert_class_to_enum_if_needed(obj)
 
-            # Build nested TOC
-            if uid.count('.') >= 1:
-                parent_level = '.'.join(uid.split('.')[:-1])
-                found_node = find_node_in_toc_tree(toc_yaml, parent_level)
+            build_nested_toc(toc_yaml, uid)
 
-                if found_node:
-                    found_node.pop('uid', 'No uid found')
-                    found_node.setdefault('items', [{'name': 'Overview', 'uid': parent_level}]).append(
-                        {'name': uid, 'uid': uid})
-                else:
-                    toc_yaml.append({'name': uid, 'uid': uid})
+    index_children = []
+    index_references = []
 
-            else:
-                toc_yaml.append({'name': uid, 'uid': uid})
+    def form_index_references_and_children(yaml_data, index_children, index_references):
+        if yaml_data[0].get('type', None) in ['package', 'module']:
+            index_children.append(yaml_data[0].get('fullName', ''))
+            index_references.append({
+                'uid': yaml_data[0].get('fullName', ''),
+                'name': yaml_data[0].get('fullName', ''),
+                'fullname': yaml_data[0].get('fullName', ''),
+                'isExternal': False
+            })
 
     for data_set in (app.env.docfx_yaml_packages,
                      app.env.docfx_yaml_modules,
@@ -233,6 +281,9 @@ def build_finished(app, exception):
                      app.env.docfx_yaml_functions):  # noqa
 
         for uid, yaml_data in iter(sorted(data_set.items())):
+
+            form_index_references_and_children(yaml_data, index_children, index_references)
+
             # Output file
             if uid.lower() in file_name_set:
                 filename = uid + "(%s)" % app.env.docfx_info_uid_types[uid]
@@ -281,16 +332,6 @@ def build_finished(app, exception):
         )
 
     index_file = os.path.join(normalized_outdir, 'index.yml')
-    index_children = []
-    index_references = []
-    for item in toc_yaml:
-        index_children.append(item.get('name', ''))
-        index_references.append({
-            'uid': item.get('name', ''),
-            'name': item.get('name', ''),
-            'fullname': item.get('name', ''),
-            'isExternal': False
-        })
 
     index_obj = [{
         'uid': 'project-' + app.config.project,

py2docfx/docfx_yaml/common.py

@@ -97,7 +97,9 @@ def convert_member(obj, reference_mapping):
             'name': obj.get('fullName', '').split('.')[-1],
             'summary': obj.get('summary', None),
             'signature': obj.get('syntax', {}).get('content', None),
+            'positionalOnlyParameters': list(map(convert_parameter_partial, obj.get('syntax', {}).get('positionalOnlyParameters', []))),
             'parameters': list(map(convert_parameter_partial, obj.get('syntax', {}).get('parameters', []))),
+            'keywordOnlyParameters': list(map(convert_parameter_partial, obj.get('syntax', {}).get('keywordOnlyParameters', []))),
             'return': convert_return(obj.get('syntax', {}).get('return', {}), reference_mapping),
             'exceptions': obj.get('exceptions', None),
             'examples': obj.get('example', None),
@@ -167,7 +169,9 @@ def get_constructor_and_variables(syntax_object, reference_mapping):
     if syntax_object:
         constructor_object = {
             'syntax': syntax_object.get('content', None),
-            'parameters': list(map(convert_parameter_partial, syntax_object.get('parameters', [])))
+            'positionalOnlyParameters': list(map(convert_parameter_partial, syntax_object.get('positionalOnlyParameters', []))),
+            'parameters': list(map(convert_parameter_partial, syntax_object.get('parameters', []))),
+            'keywordOnlyParameters': list(map(convert_parameter_partial, syntax_object.get('keywordOnlyParameters', []))),
         }
 
         return remove_empty_values(constructor_object), list(map(convert_variable_partial, syntax_object.get('variables', [])))

py2docfx/docfx_yaml/parameter_utils.py

@@ -214,7 +214,7 @@ def extract_description(ret_data, app):
     nodes = ret_data.children
     description_index = None
     for node in nodes:
-        if node.tagname == "#text" and node.astext().strip() in ['–', '––']:
+        if node.tagname == "#text" and node.astext().strip() in ['–', '––', '--']:
             description_index = nodes.index(node) + 1
             break
     

py2docfx/docfx_yaml/process_doctree.py

@@ -110,6 +110,72 @@ def _resolve_reference_in_module_summary(lines):
         new_lines.append(new_line)
     return new_lines
 
+def getParameterArgs(argspec):
+    args = []
+    for arg in argspec.args:
+        args.append({'id': arg})
+    if argspec.defaults:
+        for count, default in enumerate(argspec.defaults):
+            cut_count = len(argspec.defaults)
+            # Only add defaultValue when str(default) doesn't contain object address string
+            # (object at 0x)(lambda at 0x)(function *** at 0x)
+            # inspect.getargspec method will return wrong defaults which contain object address for some default values, like sys.stdout
+            # Match the defaults with the count
+            if ' at 0x' not in str(default):
+                args[len(args) - cut_count +
+                    count]['defaultValue'] = str(default)
+            else:
+                args[len(args) - cut_count +
+                    count]['isRequired'] = False
+    return args
+
+def getKeywordOnlyParameters(argspec):
+    keyword_only_args = []
+    # check if there is keyword only args
+    if argspec.kwonlyargs:
+        count = 0
+        for arg in argspec.kwonlyargs:
+            keyword_only_args.append({'id': arg})
+            # try get the default value for keyword only args
+            if argspec.kwonlydefaults:
+                kwarg_default = argspec.kwonlydefaults.get(arg, None)
+                if kwarg_default:
+                    keyword_only_args[count]['defaultValue'] = str(kwarg_default)
+            count += 1
+    return keyword_only_args
+
+def getpositionalOnlyParameters(signature):
+    positional_only_param = []
+    # check if there is positional only params
+    positional_only_param_list = [param
+            for param in signature.parameters.values()
+            if param.kind == param.POSITIONAL_ONLY]
+    if positional_only_param_list:
+        count = 0
+        for po_param in positional_only_param_list:
+            if po_param.name != 'self':
+                positional_only_param.append({'id': po_param.name})
+
+                try:
+                    default_value = str(po_param.default)
+                except KeyError:
+                    # if the default value is not available, set it to inspect._empty
+                    default_value = "<class 'inspect._empty'>"
+                
+                if default_value != "<class 'inspect._empty'>":
+                    positional_only_param[count]['defaultValue'] = default_value
+                
+                count += 1
+    return positional_only_param
+
+def removePositonalOnlyFromArgs(args, positional_only_params):
+    # Create a set of ids from positional_only_params for efficient lookup
+    positional_only_params_ids = set(obj['id'] for obj in positional_only_params)
+
+    # Filter out objects from args array whose id is in the set of positional_only_params_ids
+    filtered_a = [obj for obj in args if obj['id'] not in positional_only_params_ids]
+
+    return filtered_a
 
 def _create_datam(app, cls, module, name, _type, obj, lines=None):
     """
@@ -120,26 +186,23 @@ def _create_datam(app, cls, module, name, _type, obj, lines=None):
         lines = []
     short_name = name.split('.')[-1]
     args = []
-
+    keyword_only_args = []
+    positional_only_params = []
     try:
         if _type in [CLASS, METHOD, FUNCTION]:
-            if not (_type  == CLASS and isinstance(type(obj).__call__, type(EnumMeta.__call__))):                             
-                argspec = inspect.getfullargspec(obj)  # noqa
-                for arg in argspec.args:
-                    args.append({'id': arg})
-                if argspec.defaults:
-                    for count, default in enumerate(argspec.defaults):
-                        cut_count = len(argspec.defaults)
-                        # Only add defaultValue when str(default) doesn't contain object address string
-                        # (object at 0x)(lambda at 0x)(function *** at 0x)
-                        # inspect.getargspec method will return wrong defaults which contain object address for some default values, like sys.stdout
-                        # Match the defaults with the count
-                        if ' at 0x' not in str(default):
-                            args[len(args) - cut_count +
-                                count]['defaultValue'] = str(default)
-                        else:
-                            args[len(args) - cut_count +
-                                count]['isRequired'] = False
+            if not (_type  == CLASS and isinstance(type(obj).__call__, type(EnumMeta.__call__))):       
+                signature = inspect.signature(obj)
+                argspec = inspect.getfullargspec(obj)
+
+                args = getParameterArgs(argspec)
+                keyword_only_args = getKeywordOnlyParameters(argspec)
+                positional_only_params = getpositionalOnlyParameters(signature)
+
+                # The args will contian both regular args and positional only params
+                # so we need to remove the positional only args from params
+                if positional_only_params:
+                    args = removePositonalOnlyFromArgs(args, positional_only_params)
+
     except Exception as e:
         print("Can't get argspec for {}: {}. Exception: {}".format(type(obj), name, e))
 
@@ -160,9 +223,14 @@ def _create_datam(app, cls, module, name, _type, obj, lines=None):
         if summary:
             datam['summary'] = summary.strip(" \n\r\r")
 
-    if args:
+    if args or keyword_only_args or positional_only_params:
         datam['syntax'] = {}
-        datam['syntax']['parameters'] = args
+        if args:
+            datam['syntax']['parameters'] = args
+        if keyword_only_args:
+            datam['syntax']['keywordOnlyParameters'] = keyword_only_args
+        if positional_only_params:
+            datam['syntax']['positionalOnlyParameters'] = positional_only_params
     if cls:
         datam[CLASS] = cls
     if _type in [CLASS, MODULE, PACKAGE]:

py2docfx/docfx_yaml/tests/roots/test-build-finished/code_with_signature_and_docstring.py

@@ -0,0 +1,16 @@
+class TestClass:
+    def test_method(self,
+                    positional_only_param,
+                    /,
+                    parameter,
+                    *,
+                    keyword_only_arg,
+                    **kwargs):
+        """
+        This is a test method
+        
+        :param str parameter: This is a parameter
+        :keyword bool keyword_only_arg: This is a keyword only argument
+        """
+        pass
+    

py2docfx/docfx_yaml/tests/roots/test-build-finished/conf.py

@@ -0,0 +1,24 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+
+extensions = ["sphinx.ext.autodoc","sphinx.ext.napoleon", "yaml_builder"]
+
+class includeTest:
+    pass
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+autodoc_mock_imports = [
+    'dummy'
+]
+
+pygments_style = 'sphinx'
+
+napoleon_use_admonition_for_examples = True
+
+nitpicky = True
+
+napoleon_preprocess_types=True

py2docfx/docfx_yaml/tests/roots/test-method-arguments/code_with_all_arg_types.py

@@ -0,0 +1,10 @@
+class TestClass:
+    def test_method(self,
+                    positional_only_param = 10,
+                    /,
+                    parameter_with_default_value=True,
+                    *,
+                    keyword_only_arg = "keyword_only_arg_default_value",
+                    **kwargs):
+        pass
+    

py2docfx/docfx_yaml/tests/roots/test-method-arguments/conf.py

@@ -0,0 +1,24 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+
+extensions = ["sphinx.ext.autodoc","sphinx.ext.napoleon", "yaml_builder"]
+
+class includeTest:
+    pass
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+autodoc_mock_imports = [
+    'dummy'
+]
+
+pygments_style = 'sphinx'
+
+napoleon_use_admonition_for_examples = True
+
+nitpicky = True
+
+napoleon_preprocess_types=True

py2docfx/docfx_yaml/tests/test_build_finished.py

@@ -0,0 +1,133 @@
+import pytest
+
+from translator import translator
+from build_finished import build_finished, merge_data
+
+from .utils.test_utils import prepare_app_envs,load_rst_transform_to_doctree
+
+@pytest.mark.sphinx('yaml', testroot='build-finished')
+def test_build_finished(app):
+    # Test data definition
+    objectToGenXml = 'code_with_signature_and_docstring.TestClass'
+    objectToGenXmlType = 'class'
+
+    # Arrange
+    prepare_app_envs(app, objectToGenXml)
+    doctree = load_rst_transform_to_doctree(app, objectToGenXmlType, objectToGenXml)
+
+    translator(app, '', doctree)
+
+    # Assert before build_finished
+    target_node = app.env.docfx_yaml_classes[objectToGenXml][1]['syntax']
+    parameter_node = target_node['parameters'][0]
+    keyword_only_arg_node = target_node['keywordOnlyParameters'][0]
+    positional_only_param_node = target_node['positionalOnlyParameters'][0]
+
+    assert (parameter_node['id'] == 'self')
+    parameter_node = target_node['parameters'][1]
+    assert (parameter_node['id'] == 'parameter')
+    assert ('type' not in parameter_node.keys())
+    assert (keyword_only_arg_node['id'] == 'keyword_only_arg')
+    assert ('type' not in keyword_only_arg_node.keys())
+    assert (positional_only_param_node['id'] == 'positional_only_param')
+    assert ('isRequired' not in positional_only_param_node.keys())
+    # Act
+    build_finished(app, None)
+
+    # Assert after build_finished
+    target_node = app.env.docfx_yaml_classes[objectToGenXml][1]['syntax']
+    parameter_node = target_node['parameters'][0]
+    keyword_only_arg_node = target_node['keywordOnlyParameters'][0]
+    positional_only_param_node = target_node['positionalOnlyParameters'][0]
+
+    assert (parameter_node['id'] == 'parameter')
+    assert (parameter_node['type'] == ['<xref:str>'])
+    assert (keyword_only_arg_node['id'] == 'keyword_only_arg')
+    assert (keyword_only_arg_node['type'] == ['<xref:bool>'])
+    assert (positional_only_param_node['id'] == 'positional_only_param')
+    assert (positional_only_param_node['isRequired'] == True)
+
+def test_merge_data():
+    # Test data definition
+    obj = {
+        'uid': 'test_uid',
+        'type': 'test_type',
+        'syntax': {
+            'parameters': [{'id': 'param1'}],
+            'keywordOnlyParameters': [{'id': 'kwarg1'}]
+        }
+    }
+    info_field_data = {
+        'test_uid': {
+            'type': 'test_type',
+            'parameters': [{'id': 'param2'}],
+            'keywordOnlyParameters': [{'id': 'kwarg2'}]
+        }
+    }
+    yaml_data = []
+
+    # Call the function to test
+    merge_data(obj, info_field_data, yaml_data)
+
+    # Assert the results
+    assert 'type' in info_field_data['test_uid']
+    assert info_field_data['test_uid']['type'] == 'test_type'
+    assert len(obj['syntax']['parameters']) == 2
+    assert len(obj['syntax']['keywordOnlyParameters']) == 2
+    assert obj['syntax']['parameters'][0]['id'] == 'param2'
+    assert obj['syntax']['parameters'][1]['id'] == 'param1'
+    assert obj['syntax']['keywordOnlyParameters'][0]['id'] == 'kwarg2'
+    assert obj['syntax']['keywordOnlyParameters'][1]['id'] == 'kwarg1'
+
+def test_merge_data_no_syntax():
+    # Test data definition
+    obj = {
+        'uid': 'test_uid',
+        'type': 'test_type'
+    }
+    info_field_data = {
+        'test_uid': {
+            'type': 'test_type',
+            'parameters': [{'id': 'param1'}],
+            'keywordOnlyParameters': [{'id': 'kwarg1'}]
+        }
+    }
+    yaml_data = []
+
+    # Call the function to test
+    merge_data(obj, info_field_data, yaml_data)
+
+    # Assert the results
+    assert 'syntax' in obj
+    assert len(obj['syntax']['parameters']) == 1
+    assert len(obj['syntax']['keywordOnlyParameters']) == 1
+    assert obj['syntax']['parameters'][0]['id'] == 'param1'
+    assert obj['syntax']['keywordOnlyParameters'][0]['id'] == 'kwarg1'
+
+def test_merge_data_added_attribute():
+    # Test data definition
+    obj = {
+        'uid': 'test_uid',
+        'type': 'test_type',
+        'syntax': {
+            'parameters': [{'id': 'param1'}],
+            'keywordOnlyParameters': [{'id': 'kwarg1'}],
+            'added_attribute': [{'uid': 'attr1'}]
+        }
+    }
+    info_field_data = {
+        'test_uid': {
+            'type': 'test_type',
+            'parameters': [{'id': 'param2'}],
+            'keywordOnlyParameters': [{'id': 'kwarg2'}]
+        }
+    }
+    yaml_data = []
+
+    # Call the function to test
+    merge_data(obj, info_field_data, yaml_data)
+
+    # Assert the results
+    assert 'added_attribute' not in obj['syntax']
+    assert len(yaml_data) == 1
+    assert yaml_data[0]['uid'] == 'attr1'

py2docfx/docfx_yaml/tests/test_method_arguments.py

@@ -0,0 +1,35 @@
+import pytest
+
+from sphinx.testing import restructuredtext
+from sphinx.io import SphinxStandaloneReader
+from sphinx import addnodes
+from translator import translator
+
+from .utils.test_utils import prepare_app_envs,prepare_refered_objects,load_rst_transform_to_doctree, do_autodoc
+@pytest.mark.sphinx('dummy', testroot='method-arguments')
+def test_method_with_three_type_of_arguments(app):
+    # Test data definition
+    objectToGenXml = 'code_with_all_arg_types.TestClass'
+    objectToGenXmlType = 'class'
+
+    # Arrange
+    prepare_app_envs(app, objectToGenXml)
+    doctree = load_rst_transform_to_doctree(app, objectToGenXmlType, objectToGenXml)
+    
+    # Act
+    translator(app, '', doctree)
+
+    # Assert
+    argumentsDetail = app.env.docfx_yaml_classes[objectToGenXml][1]['syntax']
+    parameters = argumentsDetail.get('parameters', None)
+    keywordOnlyParameters = argumentsDetail.get('keywordOnlyParameters', None)
+    positionalOnlyParameters = argumentsDetail.get('positionalOnlyParameters', None)
+    assert (parameters != None)
+    assert (keywordOnlyParameters != None)
+    assert (positionalOnlyParameters != None)
+    assert (parameters[1]['id'] == 'parameter_with_default_value')
+    assert (parameters[1]['defaultValue'] == 'True')
+    assert (keywordOnlyParameters[0]['id'] == 'keyword_only_arg')
+    assert (keywordOnlyParameters[0]['defaultValue'] == 'keyword_only_arg_default_value')
+    assert (positionalOnlyParameters[0]['id'] == 'positional_only_param')
+    assert (positionalOnlyParameters[0]['defaultValue'] == '10')

py2docfx/docfx_yaml/translator.py

@@ -123,6 +123,7 @@ def translator(app, docname, doctree):
     def _get_full_data(node, module_name):
         data = {
             'parameters': [],
+            'keywordOnlyParameters': [],
             'variables': [],
             'exceptions': [],
             'return': {},
@@ -165,16 +166,20 @@ def translator(app, docname, doctree):
                 if _is_single_paragraph(fieldbody):
                     #_data = parse_parameter(ret_data, fieldtype)
                     _data = parameter_utils.parse_parameter(content[0], fieldtype, app)
-                    if fieldtype in ['Parameters', 'Keyword']:
+                    if fieldtype == 'Parameters':
                         data['parameters'].append(_data)
+                    elif fieldtype == 'Keyword':
+                        data['keywordOnlyParameters'].append(_data)
                     else:
                         _data['id'] = _parse_variable_id(content[0].astext())
                         data['variables'].append(_data)
                 else:
                     for child in content[0]:
                         _data = parameter_utils.parse_parameter(child[0], fieldtype, app)
-                        if fieldtype in ['Parameters', 'Keyword']:
+                        if fieldtype in ['Parameters']:
                             data['parameters'].append(_data)
+                        elif fieldtype == 'Keyword':
+                            data['keywordOnlyParameters'].append(_data)
                         else:
                             _data['id'] = _parse_variable_id(child.astext())
                             data['variables'].append(_data)
@@ -371,6 +376,9 @@ def translator(app, docname, doctree):
                 if 'parameters' in current_data and 'parameters' in field_list_data:
                     current_data['parameters'].extend(field_list_data['parameters'])
                     field_list_data.pop('parameters')
+                if 'keywordOnlyParameters' in current_data and 'keywordOnlyParameters' in field_list_data:
+                    current_data['keywordOnlyParameters'].extend(field_list_data['keywordOnlyParameters'])
+                    field_list_data.pop('keywordOnlyParameters')
                 if 'variables' in current_data and 'variables' in field_list_data:
                     current_data['variables'].extend(field_list_data['variables'])
                     field_list_data.pop('variables')

{py2docfx-0.1.1rc1538122.dist-info → py2docfx-0.1.1rc1634530.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: py2docfx
-Version: 0.1.1rc1538122
+Version: 0.1.1rc1634530
 Summary: A package built based on Sphinx which download source code package and generate yaml files supported by docfx.
 Author: Microsoft Corporation
 License: MIT License

{py2docfx-0.1.1rc1538122.dist-info → py2docfx-0.1.1rc1634530.dist-info}/RECORD

@@ -52,9 +52,9 @@ py2docfx/convert_prepare/tests/data/subpackage/azure-mgmt-containerservice/azure
 py2docfx/convert_prepare/tests/data/subpackage/azure-mgmt-containerservice/azure/mgmt/containerservice/v2018_03_31/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 py2docfx/convert_prepare/tests/data/subpackage/azure-mgmt-containerservice/azure/mgmt/containerservice/v2018_03_31/models.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 py2docfx/docfx_yaml/__init__.py,sha256=KCEizAXv-SXtrYhvFfLHdBWDhz51AA9uagaeTL-Itpo,100
-py2docfx/docfx_yaml/build_finished.py,sha256=jf8--IvekegnTs6Qx9H31TlDNZA6E5yPWaInmHH9QbA,13996
+py2docfx/docfx_yaml/build_finished.py,sha256=kJemkgnh9NIzn4E8jcAIaP7vb7wcHzdLl7yWUjoZbi8,14218
 py2docfx/docfx_yaml/build_init.py,sha256=lAw-fnBVQbySfZ7Sut_NpFQUjnqLOmnGQrTBBH2RXcg,1860
-py2docfx/docfx_yaml/common.py,sha256=Tl6OPSIcvPjFw1AvWt5Mun8pQr9NtUGQnk4zh474Py0,6316
+py2docfx/docfx_yaml/common.py,sha256=UN1MUmjUoN1QSFDR1Cm_bfRuHr6FQiOe5VQV6s8xzjc,6841
 py2docfx/docfx_yaml/convert_class.py,sha256=boKDaxnXbnLxja62UFXi3eChGDB_WBW6ouUUJgOhdpE,2098
 py2docfx/docfx_yaml/convert_enum.py,sha256=Kyx48WRl-48O7uv4s-Np1oD9uAd3AXL5uHb7jUsnfFg,2022
 py2docfx/docfx_yaml/convert_module.py,sha256=8UVjPn4krVfu7CgETAEBesYZyLdPthVXg7MXknni6aQ,2088
@@ -62,16 +62,18 @@ py2docfx/docfx_yaml/convert_package.py,sha256=R8dTHQXjoztHQ3bkBBchPx0k179IVr_e71
 py2docfx/docfx_yaml/directives.py,sha256=zVVuNM_6AU9G6sbqL1UAyHHgPe7bkBWbthXI-PO5ez0,879
 py2docfx/docfx_yaml/miss_reference.py,sha256=Btoj9wAvA4u_wU7JHH0Cei3910N8a7MS34OUqJvXAd4,2443
 py2docfx/docfx_yaml/nodes.py,sha256=tBDi35jLJArlobl07DKOkmH2qz7dudXLp_kTUfR_r2w,412
-py2docfx/docfx_yaml/parameter_utils.py,sha256=vCol5q2SJd1ymuyJdE_-62Tau9RP7PewQdKSimcfQuo,8700
-py2docfx/docfx_yaml/process_doctree.py,sha256=iKs1fsyo-1_P3RzpZBzD8G9hcOTGO78esWNZLXvSx2g,14866
+py2docfx/docfx_yaml/parameter_utils.py,sha256=zGSIQrUfbXf9PUK-W_1K83Uo5Zk797Zlze6aMurbHIA,8706
+py2docfx/docfx_yaml/process_doctree.py,sha256=Ve5kYoxmsJ-lq_UvfB5fldN87Nrtlm0APF0IGHWCrYg,17663
 py2docfx/docfx_yaml/return_type_utils.py,sha256=nmdCUOvwdYk2jF6RqmOvU6gjXmXUTPUeCqyHPdKZNUQ,7483
 py2docfx/docfx_yaml/settings.py,sha256=JQZNwFebczl-zn8Yk2taAGANRi-Hw8hywtDWxqXXFyQ,373
-py2docfx/docfx_yaml/translator.py,sha256=kJwGiXkiJgK3HPcVNX4qmt2Xwd77_DXS9Vd7LyGCFZo,25366
+py2docfx/docfx_yaml/translator.py,sha256=li20Sdu-j1V7oK1iaxWw9mo0KSJOlh4FLSnwmu6UxBQ,25912
 py2docfx/docfx_yaml/utils.py,sha256=m5jC_qP2NKqzUx_z0zgZ-HAmxQdNTpJYKkL_F9vGeII,1555
 py2docfx/docfx_yaml/writer.py,sha256=0ZqyVGDHa4Cr3NsuOPRf4pGUStl6g6IBxpSgIZeDT9I,34683
 py2docfx/docfx_yaml/yaml_builder.py,sha256=qSxXVS4iFCc1ZdL5QzLrv8hy3LHIQCrhO4WcTp01vag,2575
 py2docfx/docfx_yaml/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 py2docfx/docfx_yaml/tests/conftest.py,sha256=CykkZxaDZ-3a1EIQdGBieSmHL9FdyTE2xTJZe9QgKcg,1214
+py2docfx/docfx_yaml/tests/test_build_finished.py,sha256=ShCRhIHGu2IUaM6iWsC0w9i_qmdc_kadPE3oPRBBZbQ,4720
+py2docfx/docfx_yaml/tests/test_method_arguments.py,sha256=Cvj9aoADtacKciVN8nempXW-KQL8nujSa9GNVuk6l_8,1578
 py2docfx/docfx_yaml/tests/test_numpy_syntax.py,sha256=ssb3J_-Jzjybhh4eycCA_LkXbGflyZyIUAiTjlEYLiw,863
 py2docfx/docfx_yaml/tests/test_translator_attributes.py,sha256=qZCsQGffq31k3UzpXkJpycplOXIq9gi2SxY6vu0DTfw,5224
 py2docfx/docfx_yaml/tests/test_translator_contents.py,sha256=lVCWbBIQk2oPFqsKK9gIb-b5DixutMabWjP7x03oj4s,1746
@@ -83,6 +85,10 @@ py2docfx/docfx_yaml/tests/test_translator_rst_returns.py,sha256=BL3nOMMTPzNPJk-P
 py2docfx/docfx_yaml/tests/test_translator_signatures.py,sha256=DM51EOb4UXLkrO1-4cQQQvvX210goAsnxKJH-4A2U2Q,1537
 py2docfx/docfx_yaml/tests/test_writer_table.py,sha256=UnGYXQ-QVxin_e-HGZAHdg1LSFV0qc480ZNsqPN9OYc,1444
 py2docfx/docfx_yaml/tests/test_writer_uri.py,sha256=L9eFHZndD6H7nkznJ9Bw0v8xh9IegDlhhGFHBz9EHmM,1745
+py2docfx/docfx_yaml/tests/roots/test-build-finished/code_with_signature_and_docstring.py,sha256=qvcKWL68C2aDTP8JT022nMV4EdZ50vhxVshMrHVO2sY,449
+py2docfx/docfx_yaml/tests/roots/test-build-finished/conf.py,sha256=L8vIFmO546PCQks50Gif_uTBwC3cppohXrQaogfyRF8,410
+py2docfx/docfx_yaml/tests/roots/test-method-arguments/code_with_all_arg_types.py,sha256=jK4M4ejeVWedhHJ_s9L9wEEqJmk0wOF8-yuoIaA6fZU,322
+py2docfx/docfx_yaml/tests/roots/test-method-arguments/conf.py,sha256=L8vIFmO546PCQks50Gif_uTBwC3cppohXrQaogfyRF8,410
 py2docfx/docfx_yaml/tests/roots/test-numpy-syntax/code_with_numpy.py,sha256=-7ZN5VPVQfj0-jwPZW_jkIe78B17j5cbXA4f2ZgQIFc,219
 py2docfx/docfx_yaml/tests/roots/test-numpy-syntax/conf.py,sha256=SczEhbCZ_zuTYW1ZyrB2VJ4FRh6B-q58SN7ZZ5INCeM,394
 py2docfx/docfx_yaml/tests/roots/test-translator-attributes/code_with_docstring.py,sha256=5JDlpC9Pm-8Bob2Qvqq58Nudk4n26nhHdOiNULrSXeY,326
@@ -112,7 +118,7 @@ py2docfx/docfx_yaml/tests/roots/test-writer-table/conf.py,sha256=avcbnIOV2mlGQwh
 py2docfx/docfx_yaml/tests/roots/test-writer-uri/code_with_uri.py,sha256=bzWTZpY2yf_By2bOSl1GFaY3BsZpkAvwQuGztlcHKkQ,537
 py2docfx/docfx_yaml/tests/roots/test-writer-uri/conf.py,sha256=avcbnIOV2mlGQwhMQJZC4W6UGRBRhnq1QBxjPWlySxQ,260
 py2docfx/docfx_yaml/tests/utils/test_utils.py,sha256=d0OYSUQ6NyoZx5mlLdNGGNhiNmmQhjVT4hQ6jY3VE_M,3383
-py2docfx-0.1.1rc1538122.dist-info/METADATA,sha256=AgLm_FNB3wg6R1EQyC9LHpJIq8q49FqvoJeJ2TYcfLM,599
-py2docfx-0.1.1rc1538122.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-py2docfx-0.1.1rc1538122.dist-info/top_level.txt,sha256=5dH2uP81dczt_qQJ38wiZ-gzoVWasfiJALWRSjdbnYU,9
-py2docfx-0.1.1rc1538122.dist-info/RECORD,,
+py2docfx-0.1.1rc1634530.dist-info/METADATA,sha256=wJWdP3fNN10kOVuRl7qfKg1-rdZXDreGXUcPVrkyI7s,599
+py2docfx-0.1.1rc1634530.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+py2docfx-0.1.1rc1634530.dist-info/top_level.txt,sha256=5dH2uP81dczt_qQJ38wiZ-gzoVWasfiJALWRSjdbnYU,9
+py2docfx-0.1.1rc1634530.dist-info/RECORD,,