Merge pull request #84 from docascode/yitian/fix-source

Fix error of using ReferenceAutomation repo as the source code repo. And fix syntax field content.

docfx_yaml/directives.py

@@ -4,32 +4,18 @@
 This module is used to add extra supported directives to sphinx.
 """
 
+from docutils.parsers.rst.directives.admonitions import BaseAdmonition
 from docutils.parsers.rst import Directive
 from docutils import nodes
 
 from .nodes import remarks
 
 
-class RemarksDirective(Directive):
+class RemarksDirective(BaseAdmonition):
     """
     Class to enable remarks directive.
     """
-
-    # Enable content in the directive
-    has_content = True
-
-    # Directive class must override run function.
-    def run(self):
-        self.assert_has_content()
-
-        text = '\n'.join(self.content)
-
-        return_nodes = []
-
-        node = remarks('', text)
-        return_nodes.append(node)
-
-        return return_nodes
+    node_class = remarks
 
 class TodoDirective(Directive):
     """

docfx_yaml/extension.py

@@ -55,7 +55,7 @@ class Bcolors:
 REFMETHOD = 'meth'
 REFFUNCTION = 'func'
 INITPY = '__init__.py'
-REF_PATTERN = ':(func|class|meth|mod|ref):`~?[a-zA-Z_\.<> ]*?`'
+REF_PATTERN = ':(py:)?(func|class|meth|mod|ref):`~?[a-zA-Z_\.<> ]*?`'
 
 
 def build_init(app):
@@ -179,7 +179,7 @@ def _resolve_reference_in_module_summary(lines):
                 # match string like ':func:`~***`' or ':func:`***`'
                 index = matched_str.index('~') if '~' in matched_str else matched_str.index('`')
                 ref_name = matched_str[index+1:-1]
-            new_line = new_line.replace(matched_str, '@' + ref_name)
+            new_line = new_line.replace(matched_str, '<xref:{}>'.format(ref_name))
         new_lines.append(new_line)
     return new_lines
 
@@ -282,7 +282,8 @@ def _update_friendly_package_name(path):
         'langs': ['python'],
     }
 
-    if not datam['source']['remote']['repo']:
+    if not datam['source']['remote']['repo'] or \
+    datam['source']['remote']['repo'] == 'https://apidrop.visualstudio.com/Content%20CI/_git/ReferenceAutomation':
         del(datam['source'])
 
     # Only add summary to parts of the code that we don't get it from the monkeypatch
@@ -496,7 +497,7 @@ def convert_module_to_package_if_needed(obj):
 
     toc_yaml = []
     # Used to record filenames dumped to avoid confliction
-    # caused by Windows case insenstive file system
+    # caused by Windows case insensitive file system
     file_name_set = set()
 
     # Order matters here, we need modules before lower level classes,
@@ -532,8 +533,11 @@ def convert_module_to_package_if_needed(obj):
                                     " {}".format(obj['uid']))
                             # Zip 2 param lists until the long one is exhausted
                             for args, docs in zip_longest(arg_params, doc_params, fillvalue={}):
-                                args.update(docs)
-                                merged_params.append(args)
+                                if len(args) == 0:
+                                    merged_params.append(docs)
+                                else:
+                                    args.update(docs)
+                                    merged_params.append(args)
                     obj['syntax'].update(app.env.docfx_info_field_data[obj['uid']])
                     if merged_params:
                         obj['syntax']['parameters'] = merged_params
@@ -674,6 +678,7 @@ def convert_module_to_package_if_needed(obj):
                 'items': [{
                     'uid': 'project-' + app.config.project,
                     'name': app.config.project,
+                    'fullName': app.config.project,
                     'langs': ['python'],
                     'type': 'package',
                     'summary': '',

docfx_yaml/monkeypatch.py

@@ -12,7 +12,6 @@
 from .nodes import remarks
 
 TYPE_SEP_PATTERN = '(\[|\]|, |\(|\))'
-REF_PATTERN = ':(func|class|meth|mod|ref|any):`~?([a-zA-Z_\.<> ]*?)`'
 
 def _get_desc_data(node):
     assert node.tagname == 'desc'
@@ -313,6 +312,15 @@ def extract_exception_desc(field_object):
 
     class PatchedDocFieldTransformer(docfields.DocFieldTransformer):
 
+        @staticmethod
+        def type_mapping(type_name):
+            mapping = {
+                "staticmethod": "method",
+                "exception": "class"
+            }
+
+            return mapping[type_name] if type_name in mapping else type_name
+
         def __init__(self, directive):
             self.directive = directive
             super(PatchedDocFieldTransformer, self).__init__(directive)
@@ -325,9 +333,8 @@ def transform_all(self, node):
             name, uid = _get_desc_data(node.parent)
             for child in node:
                 if isinstance(child, remarks):
-                    remarks_string = child.astext()
-                    data['remarks'] = re.sub(REF_PATTERN, lambda x: '@' + x.group(2), remarks_string)
-                    node.remove(child)
+                    remarks_string = transform_node(child)
+                    data['remarks'] = remarks_string
                 elif isinstance(child, addnodes.desc):
                     if child.get('desctype') == 'attribute':
                         attribute_map = {} # Used for detecting duplicated attributes in intermediate data and merge them
@@ -423,7 +430,7 @@ def transform_all(self, node):
             for key, val in data.copy().items():
                 if not val:
                     del data[key]
-            data['type'] = node.parent["desctype"] if "desctype" in node.parent else 'unknown'
+            data['type'] = PatchedDocFieldTransformer.type_mapping(node.parent["desctype"]) if "desctype" in node.parent else 'unknown'
             self.directive.env.docfx_info_field_data[uid] = data
             super(PatchedDocFieldTransformer, self).transform_all(node)
 

docfx_yaml/nodes.py

@@ -6,7 +6,7 @@
 
 from docutils import nodes
 
-class remarks(nodes.paragraph):
+class remarks(nodes.paragraph, nodes.Element):
     """
     New node for remarks messages.
     """

docfx_yaml/writer.py

@@ -599,7 +599,8 @@ def visit_image(self, node):
         try:
             image_name = '/'.join(node.attributes['uri'].split('/')[node.attributes['uri'].split('/').index('_static')-1:])
         except ValueError as e:
-            sys.exit("Image not found where expected {}".format(node.attributes['uri']))
+            print("Image not found where expected {}".format(node.attributes['uri']))
+            raise nodes.SkipNode
         image_name = ''.join(image_name.split())
         self.new_state(0)
         if 'alt' in node.attributes:
@@ -763,7 +764,9 @@ def depart_admonition(self, node):
     visit_warning = _visit_admonition
     depart_warning = _make_depart_admonition('warning')
     visit_seealso = _visit_admonition
-    depart_seealso = _make_depart_admonition('seealso')
+
+    def depart_seealso(self, node):
+        self.end_state()
 
     def visit_versionmodified(self, node):
         self.new_state(0)
@@ -878,17 +881,17 @@ def visit_substitution_definition(self, node):
 
     def visit_pending_xref(self, node):
         if 'refdomain' in node.attributes and node.attributes['refdomain'] == 'py':
-            self.add_text('@{}'.format(node.attributes['reftarget']))
+            self.add_text('<xref:{}>'.format(node.attributes['reftarget']))
         raise nodes.SkipNode
 
     def depart_pending_xref(self, node):
         pass
 
     def visit_reference(self, node):
         if 'refid' in node.attributes:
-            self.add_text('@{}'.format(node.attributes['refid']))
+            self.add_text('<xref:{}>'.format(node.attributes['refid']))
         elif 'refuri' in node.attributes:
-            if 'http' in node.attributes['refuri']:
+            if 'http' in node.attributes['refuri'] or node.attributes['refuri'][0] == '/':
                 self.add_text('[{}]({})'.format(node.astext(), node.attributes['refuri']))
             else:
                 # only use id in class and func refuri if its id exists
@@ -904,7 +907,7 @@ def visit_reference(self, node):
                     pos = node.attributes['refuri'].find('.html')
                     if pos != -1:
                         node.attributes['refuri'] = node.attributes['refuri'][0: pos]
-                self.add_text('@{}'.format(node.attributes['refuri']))
+                self.add_text('<xref:{}>'.format(node.attributes['refuri']))
         else:
             self.add_text('{}<!-- {} -->'.format(node.tagname, json.dumps(node.attributes)))
         raise nodes.SkipNode

setup.py

@@ -13,7 +13,7 @@
 
 setup(
     name='sphinx-docfx-yaml',
-    version='1.2.43',
+    version='1.2.57',
     author='Eric Holscher',
     author_email='eric@ericholscher.com',
     url='https://github.com/ericholscher/sphinx-docfx-yaml',

tests/example/format/rst/foo.py

@@ -184,6 +184,6 @@ class InternalFoo(object):
 
 class InheritFoo(Foo, dict):
     """ Docstring of :class:`format.rst.foo.InheritFoo`.
-    This class inherit from two classes: :class:`format.rst.foo.Foo` and :class:`format.rst.foo.
+    This class inherit from two classes: :class:`format.rst.foo.Foo` and :class:`format.rst.foo`.
     """
     pass

tests/test_yaml.py

@@ -134,8 +134,8 @@ def test_summary(self):
 
                 self.assertEqual(
                     data['items'][0]['summary'].replace('\n', ' ').strip(),
-                    'Docstring of internal class @format.rst.foo.FooException.InternalFoo. '
-                    'This class is an internal class of @format.rst.foo.FooException.'
+                    'Docstring of internal class <xref:format.rst.foo.FooException.InternalFoo>. '
+                    'This class is an internal class of <xref:format.rst.foo.FooException>.'
                 )
 
             with open(os.path.join(self.build_path, self.yaml_files['module_files']['numpy'][0])) as f:
@@ -144,7 +144,7 @@ def test_summary(self):
 
                 self.assertEqual(
                     data['items'][0]['summary'].strip(),
-                    'Docstring of @format.numpy.foo module.'
+                    'Docstring of <xref:format.numpy.foo> module.'
                 )
 
             with open(os.path.join(self.build_path, self.yaml_files['package_files']['format'][1])) as f:
@@ -153,7 +153,7 @@ def test_summary(self):
 
                 self.assertEqual(
                     data['items'][0]['summary'].strip(),
-                    'Docstring of package @format.rst.'
+                    'Docstring of package <xref:format.rst>.'
                 )
 
     def test_references(self):
@@ -316,7 +316,7 @@ def test_google_format(self):
                     if item['uid'] == 'format.google.foo.Foo.method_seealso':
                         self.assertEqual(
                             item['seealsoContent'].strip(),
-                            'See also: Seealso contents. Multi-line should be supported.'
+                            'Seealso contents.\n  Multi-line should be supported.'
                         )
 
     def test_numpy_format(self):
@@ -332,7 +332,7 @@ def test_numpy_format(self):
                     if item['uid'] == 'format.numpy.foo.Foo.method_seealso':
                         self.assertEqual(
                             re.sub(r'\s+', ' ', item['seealsoContent']).strip(),
-                            'See also: @format.numpy.foo.Foo.mathod_note See also target.'
+                            '<xref:format.numpy.foo.Foo.mathod_note> See also target.'
                         )  # Test see also centent from numpy format.
 
     def test_toc(self):
@@ -435,7 +435,7 @@ def test_seealso(self):
                         )  # Test seealso field existance
 
                         self.assertIn(
-                            'Seealso contents. Multi-line should be supported.',
+                            'Seealso contents.\n  Multi-line should be supported.',
                             item['seealsoContent']
                         )  # Test seealso content