Merge pull request #16 from ericholscher/more-refactoring

A few more updates.

README.rst

@@ -77,3 +77,13 @@ This project has a few different pieces at this point.
 It's primary goal was to integrate the Azure Python SDK into the docfx tooling.
 You can read more about the pieces currently set up in the :doc:`layout`.
 
+
+Napoleon Support
+----------------
+
+We support ``sphinx.ext.napoleon`` for parsing docstrings in other formats.
+Currently all markup that maps to existing Sphinx `info field lists <http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists>`_ will work,
+along with ``Examples``.
+In order to pull examples out,
+you need the ``napoleon_use_admonition_for_examples`` set to ``True``.
+

docfx_yaml/extension.py

@@ -126,7 +126,6 @@ def _create_datam(app, cls, module, name, _type, obj, lines=None):
     if lines is None:
         lines = []
     short_name = name.split('.')[-1]
-    summary = app.docfx_transform_string('\n'.join(lines))
     args = []
     try:
         if _type in [METHOD, FUNCTION]:
@@ -182,8 +181,12 @@ def _create_datam(app, cls, module, name, _type, obj, lines=None):
         'langs': ['python'],
     }
 
-    if summary:
-        datam['summary'] = summary
+    # Only add summary to parts of the code that we don't get it from the monkeypatch
+    if _type == MODULE:
+        summary = app.docfx_transform_string('\n'.join(lines))
+        if summary:
+            datam['summary'] = summary
+
     if args or sig:
         datam['syntax'] = {}
         if args:

docfx_yaml/monkeypatch.py

@@ -209,6 +209,11 @@ def transform_all(self, node):
                     data.update(_data)
                 elif isinstance(child, addnodes.seealso):
                     data['seealso'] = transform_node(child)
+                elif isinstance(child, nodes.admonition) and 'Example' in child[0].astext():
+                    # Remove the admonition node
+                    child_copy = child.deepcopy()
+                    child_copy.pop(0)
+                    data['example'] = transform_node(child_copy)
                 else:
                     content = transform_node(child)
                     summary.append(content)

docfx_yaml/writer.py

@@ -802,9 +802,11 @@ def depart_literal_block(self, node):
         self.end_state(wrap=False)
 
     def visit_doctest_block(self, node):
+        self.add_text('```')
         self.new_state(0)
 
     def depart_doctest_block(self, node):
+        self.add_text(self.nl + '```')
         self.end_state(wrap=False)
 
     def visit_line_block(self, node):
@@ -870,20 +872,13 @@ def depart_pending_xref(self, node):
         pass
 
     def visit_reference(self, node):
-        if 'internal' in node.attributes and 'refid' in node.attributes:
+        if 'refid' in node.attributes:
             self.add_text('@{}'.format(node.attributes['refid']))
-            #self.add_text('[{}]({})'.format(node.astext(), 'xref:' + node.attributes['refid']))
-        elif 'internal' in node.attributes and 'refuri' in node.attributes:
-            self.add_text('[{}]({}.md)'.format(node.astext(), node.attributes['refuri'].replace('#', '.md#')))
         elif 'refuri' in node.attributes:
-            if ':doc:' in node.attributes['refuri']:
-                self.add_text('[{}]({}.md)'.format(node.astext(), node.attributes['refuri'][5:]))
-            else:
+            if 'http' in node.attributes['refuri']:
                 self.add_text('[{}]({})'.format(node.astext(), node.attributes['refuri']))
-        elif 'refid' in node.attributes and 'name' in node.attributes:
-            self.add_text('[{}]({})'.format(node.attributes['name'], '#' + node.attributes['refid']))
-        elif 'refid' in node.attributes:
-            self.add_text('[{}]({})'.format(node.astext(), '#' + node.attributes['refid']))
+            else:
+                self.add_text('@{}'.format(node.attributes['refuri'].replace('#', '')))
         else:
             self.add_text('{}<!-- {} -->'.format(node.tagname, json.dumps(node.attributes)))
         raise nodes.SkipNode

docs/design.rst

@@ -54,6 +54,13 @@ which happens to be quite simple,
 but only work for autodoc generated strings.
 Any other use of the Python domain will be ignored.
 
+Monkeypatch
+~~~~~~~~~~~
+
+In order to get the :ref:`info field lists` from Sphinx,
+we insert a monkeypatch in the Sphinx rendering.
+This lives in the ``docfx_yaml/monkeypatch.py`` file. 
+
 YAML syntax
 -----------
 

tests/pyexample/conf.py

@@ -21,3 +21,5 @@
 html_static_path = ['_static']
 htmlhelp_basename = 'pyexampledoc'
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'docfx_yaml.extension']
+
+napoleon_use_admonition_for_examples = True

tests/pyexample/example/nap.py

@@ -23,4 +23,9 @@ def ref(self, ext):
         See Also:
             Depends on :py:class:`example.example.Foo`
             Relative reference on :py:meth:`foo`
+
+        Examples:
+            >>> print('docblock 1')
+
+            >>> print('docblock 2')
         """

tests/test_yaml.py

@@ -204,3 +204,22 @@ def test_toc(self):
                             'example.example.Foo'
                         )
                         break
+
+    def test_examples(self):
+        """
+        Test second level toc nesting
+        """
+        with sphinx_build('pyexample'):
+            with open('_build/text/docfx_yaml/example.nap.Base.yml') as yml_file:
+                data = yaml.safe_load(yml_file)
+                for item in data['items']:
+                    if item['uid'] == 'example.nap.Base.ref':
+                        self.assertEqual(
+                            item['syntax']['example'].split('\n')[2],
+                            """>>> print('docblock 1')"""
+                        )
+                        self.assertEqual(
+                            item['syntax']['example'].split('\n')[7],
+                            """>>> print('docblock 2')"""
+                        )
+