py2docfx 0.1.1.dev1566958__py3-none-any.whl → 0.1.1.dev1592393__py3-none-any.whl

py2docfx/convert_prepare/tests/test_generate_document.py

@@ -51,4 +51,5 @@ def test_generate_document(tmp_path):
     assert not os.path.exists(os.path.join(yaml_path, "azure.dummy.yml"))
     assert not os.path.exists(os.path.join(yaml_path, "azure.yml"))
     assert os.path.exists(os.path.join(yaml_path, "toc.yml"))
+    assert os.path.exists(os.path.join(yaml_path, "index.yml"))
 

py2docfx/docfx_yaml/build_finished.py

@@ -32,25 +32,18 @@ def build_finished(app, exception):
     """
     Output YAML on the file system.
     """
-    def insert_node_to_toc_tree(toc_yaml, uid, project_name, toc_node_map):
-        name = uid.split('.')[-1] if '.' in uid and uid.startswith(uid) and project_name != uid else uid
-        cur_node = {'name': name, 'uid': uid}
-
-        # Build nested TOC
-        if uid.count('.') >= 1:
-            parent_level = '.'.join(uid.split('.')[:-1])
-            found_node = toc_node_map[parent_level] if parent_level in toc_node_map else None
-            if found_node:
-                # Remove uid if it isn't the project package page
-                if (not 'uid' in found_node) and found_node['uid'] != project_name:
-                    found_node.pop('uid', 'No uid found')
-                found_node.setdefault('items', []).append(cur_node)
-            else:
-                toc_yaml.append(cur_node)
-        else:
-            # if uid doesn't contain '.', the name needn't to simplify
-            toc_yaml.append(cur_node)
-        toc_node_map[uid] = cur_node
+    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):
@@ -100,9 +93,16 @@ def build_finished(app, exception):
         app.builder.outdir,  # Output Directory for Builder
         API_ROOT
     ))
+
+    def add_isrequired_if_needed(obj, key: str):
+        if key in obj['syntax'] and obj['type'] == 'method':
+            for args in obj['syntax'][key]:
+                if 'isRequired' not in args and 'defaultValue' not in args:
+                    args['isRequired'] = True
+    
+
     ensuredir(normalized_outdir)
-    project_name = app.config.project.replace('-','.')
-    toc_node_map = {}
+
     toc_yaml = []
     # Used to record filenames dumped to avoid confliction
     # caused by Windows case insensitive file system
@@ -139,6 +139,7 @@ def build_finished(app, exception):
                     if 'syntax' not in obj:
                         obj['syntax'] = {}
                     merged_params = []
+                    merged_kwargs = []
                     if 'parameters' in app.env.docfx_info_field_data[obj['uid']]:
                         doc_params = app.env.docfx_info_field_data[obj['uid']].get(
                             'parameters', [])
@@ -147,16 +148,29 @@ def build_finished(app, exception):
                                 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
+
+                    if 'keywordOnlyArguments' in app.env.docfx_info_field_data[obj['uid']]:
+                        kwargs_from_inspect = obj.get('syntax', {}).get('keywordOnlyArguments', [])
+                        kwargs_from_doc = app.env.docfx_info_field_data[obj['uid']].get('keywordOnlyArguments', [])
+                        if kwargs_from_inspect and kwargs_from_doc:
+                            merged_kwargs = merge_params(kwargs_from_inspect, kwargs_from_doc)
 
                     obj['syntax'].update(
                         app.env.docfx_info_field_data[obj['uid']])
+
+                    # Merging parameters and keywordOnlyArguments is required,
+                    # becasue parameters and keywordOnlyArguments can be in both signature and docstring
+                    # For positionalOnlyArguments, 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']['keywordOnlyArguments'] = merged_kwargs
 
-                    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
+                    add_isrequired_if_needed(obj, 'parameters')
+                    add_isrequired_if_needed(obj, 'keywordOnlyArguments')
+                    add_isrequired_if_needed(obj, 'positionalOnlyArguments')
 
                     # Raise up summary
                     if 'summary' in obj['syntax'] and obj['syntax']['summary']:
@@ -220,7 +234,20 @@ def build_finished(app, exception):
                 if (obj['type'] == 'class' and obj['inheritance']):
                     convert_class_to_enum_if_needed(obj)
 
-            insert_node_to_toc_tree(toc_yaml, uid, project_name, toc_node_map)
+            # 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})
 
     for data_set in (app.env.docfx_yaml_packages,
                      app.env.docfx_yaml_modules,
@@ -267,8 +294,41 @@ def build_finished(app, exception):
     with open(toc_file, 'w') as writable:
         writable.write(
             dump(
-                toc_yaml,
+                [{
+                    'name': app.config.project,
+                    'items': [{'name': 'Overview', 'uid': 'project-' + app.config.project}] + toc_yaml
+                }],
                 default_flow_style=False,
             )
         )
-    
+
+    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,
+        'name': app.config.project,
+        'fullName': app.config.project,
+        'langs': ['python'],
+        'type': 'package',
+        'kind': 'distribution',
+        'summary': '',
+        'children': index_children
+    }]
+    transformed_obj = convert_package(index_obj, app.env.docfx_info_uid_types)
+    mime = "PythonPackage"
+    if transformed_obj == None:
+        print("Unknown yml: " + yamlfile_path)
+    else:
+        # save file
+        common.write_yaml(transformed_obj, index_file, mime)
+        file_name_set.add(filename)

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),
+            'positionalOnlyArguments': list(map(convert_parameter_partial, obj.get('syntax', {}).get('positionalOnlyArguments', []))),
             'parameters': list(map(convert_parameter_partial, obj.get('syntax', {}).get('parameters', []))),
+            'keywordOnlyArguments': list(map(convert_parameter_partial, obj.get('syntax', {}).get('keywordOnlyArguments', []))),
             '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', [])))
+            'positionalOnlyArguments': list(map(convert_parameter_partial, syntax_object.get('positionalOnlyArguments', []))),
+            'parameters': list(map(convert_parameter_partial, syntax_object.get('parameters', []))),
+            'keywordOnlyArguments': list(map(convert_parameter_partial, syntax_object.get('keywordOnlyArguments', []))),
         }
 
         return remove_empty_values(constructor_object), list(map(convert_variable_partial, syntax_object.get('variables', [])))

py2docfx/docfx_yaml/process_doctree.py

@@ -110,6 +110,64 @@ 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 getkeywordOnlyArguments(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 getpositionalOnlyArguments(signature):
+    positional_only_args = []
+    # check if there is positional only args
+    positional_only_arg_list = [param
+            for param in signature.parameters.values()
+            if param.kind == param.POSITIONAL_ONLY]
+    if positional_only_arg_list:
+        count = 0
+        for po_arg in positional_only_arg_list:
+            if po_arg.name != 'self':
+                positional_only_args.append({'id': po_arg.name})
+                if po_arg.default:
+                    default_value = str(po_arg.default)
+                    if default_value != "<class 'inspect._empty'>":
+                        positional_only_args[count]['defaultValue'] = default_value
+                count += 1
+    return positional_only_args
+
+def removePositonalOnlyArgsFromArgs(args, positional_only_args):
+    for po_arg in positional_only_args:
+        for arg in args:
+            if arg['id'] == po_arg['id']:
+                args.remove(arg)
+                break
 
 def _create_datam(app, cls, module, name, _type, obj, lines=None):
     """
@@ -120,26 +178,22 @@ def _create_datam(app, cls, module, name, _type, obj, lines=None):
         lines = []
     short_name = name.split('.')[-1]
     args = []
-
+    keyword_only_args = []
+    positional_only_args = []
     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 = getkeywordOnlyArguments(argspec)
+                positional_only_args = getpositionalOnlyArguments(signature)
+
+                # The args will contian both regular args and positional only args
+                # so we need to remove the positional only args from args
+                removePositonalOnlyArgsFromArgs(args, positional_only_args)
+
     except Exception as e:
         print("Can't get argspec for {}: {}. Exception: {}".format(type(obj), name, e))
 
@@ -160,9 +214,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_args:
         datam['syntax'] = {}
-        datam['syntax']['parameters'] = args
+        if args:
+            datam['syntax']['parameters'] = args
+        if keyword_only_args:
+            datam['syntax']['keywordOnlyArguments'] = keyword_only_args
+        if positional_only_args:
+            datam['syntax']['positionalOnlyArguments'] = positional_only_args
     if cls:
         datam[CLASS] = cls
     if _type in [CLASS, MODULE, PACKAGE]:

py2docfx/docfx_yaml/translator.py

@@ -123,6 +123,7 @@ def translator(app, docname, doctree):
     def _get_full_data(node, module_name):
         data = {
             'parameters': [],
+            'keywordOnlyArguments': [],
             '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['keywordOnlyArguments'].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['keywordOnlyArguments'].append(_data)
                         else:
                             _data['id'] = _parse_variable_id(child.astext())
                             data['variables'].append(_data)

{py2docfx-0.1.1.dev1566958.dist-info → py2docfx-0.1.1.dev1592393.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: py2docfx
-Version: 0.1.1.dev1566958
+Version: 0.1.1.dev1592393
 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.1.dev1566958.dist-info → py2docfx-0.1.1.dev1592393.dist-info}/RECORD

@@ -22,7 +22,7 @@ py2docfx/convert_prepare/post_process/merge_toc.py,sha256=coyae54OB1nGcCkxz9oAu-
 py2docfx/convert_prepare/subpackage_merge/merge_root_package.py,sha256=uK96qL2asuSfo_3SZaoP8XZaUvjf5mNkr17JNbZR4Lg,1026
 py2docfx/convert_prepare/subpackage_merge/merge_toc.py,sha256=nkVqe8R0m8D6cyTYV7aIpMDXorvn4-LXfU_vIK_hJBg,1706
 py2docfx/convert_prepare/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-py2docfx/convert_prepare/tests/test_generate_document.py,sha256=hOAtib9pTFaZCS8QbYS6Dhz0hNGESDHPXumRIuIWp4Y,2415
+py2docfx/convert_prepare/tests/test_generate_document.py,sha256=BKw8pMSsygLnv6bETlA2MIVarECzfWoNo4JglxHb-T4,2480
 py2docfx/convert_prepare/tests/test_get_source.py,sha256=c22JfobgbEbWWiNzBNYpZm2yDfo5LwBioUuRwft9WZE,5858
 py2docfx/convert_prepare/tests/test_pack.py,sha256=46JWMNzknIptDVs7D3CuxcmqBr_OKMmaw1br9H7wqco,4134
 py2docfx/convert_prepare/tests/test_package_info.py,sha256=L2ax9dItnz5QNSsSjSjEcaS6UPZxiq3MwysBB1FdJxI,2262
@@ -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=X3pE0Vbhyxz0ZVqgLOd_GzVBuKh2FwApTperFlCx-g4,12884
+py2docfx/docfx_yaml/build_finished.py,sha256=rkTHnRVFnXVqIECkvmYnevgqpZcLhRgVuEr22IzdZqY,15220
 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=tk2dVLtj1v0HKI_vDXaB_1_2_PTNblHPM1_M8-lIfGQ,6833
 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
@@ -63,10 +63,10 @@ py2docfx/docfx_yaml/directives.py,sha256=zVVuNM_6AU9G6sbqL1UAyHHgPe7bkBWbthXI-PO
 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/process_doctree.py,sha256=sI3Hs-fpC8IE9kQldcrVlw4lALQgOOv0KT9Ht5BneeQ,17170
 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=Lfybbd28xflbq_CBH-8vCc3PkMNtoPPQJyKbPm_ywHs,25627
 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
@@ -112,7 +112,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.1.dev1566958.dist-info/METADATA,sha256=4uFaSfK2my-ed9IRdI6vb5deFmBHXomN4JZBo8TGf64,601
-py2docfx-0.1.1.dev1566958.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-py2docfx-0.1.1.dev1566958.dist-info/top_level.txt,sha256=5dH2uP81dczt_qQJ38wiZ-gzoVWasfiJALWRSjdbnYU,9
-py2docfx-0.1.1.dev1566958.dist-info/RECORD,,
+py2docfx-0.1.1.dev1592393.dist-info/METADATA,sha256=eciH7tuSk2d-cW9xPD3UrgWvKvOSC-lywQy1I4wICSE,601
+py2docfx-0.1.1.dev1592393.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+py2docfx-0.1.1.dev1592393.dist-info/top_level.txt,sha256=5dH2uP81dczt_qQJ38wiZ-gzoVWasfiJALWRSjdbnYU,9
+py2docfx-0.1.1.dev1592393.dist-info/RECORD,,