Merge pull request #70 from docascode/yitian/add-remarks-directive

add remarks directive

docfx_yaml/directives.py

@@ -0,0 +1,31 @@
+# coding: utf-8
+
+"""
+This module is used to add extra supported directives to sphinx.
+"""
+
+from docutils.parsers.rst import Directive
+from docutils import nodes
+
+from .nodes import remarks
+
+class RemarksDirective(Directive):
+    """
+    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

docfx_yaml/extension.py

@@ -25,6 +25,8 @@
 from .utils import transform_node, transform_string
 from .settings import API_ROOT
 from .monkeypatch import patch_docfields
+from .directives import RemarksDirective
+from .nodes import remarks
 
 
 class bcolors:
@@ -523,6 +525,10 @@ def convert_module_to_package_if_needed(obj):
                     # Raise up summary
                     if 'summary' in obj['syntax'] and obj['syntax']['summary']:
                         obj['summary'] = obj['syntax'].pop('summary')
+
+                    # 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']:
@@ -658,6 +664,10 @@ def setup(app):
         app (Application): The Sphinx application instance
 
     """
+
+    app.add_node(remarks, html = (remarks.visit_remarks, remarks.depart_remarks))
+    app.add_directive('remarks', RemarksDirective)
+
     app.connect('builder-inited', build_init)
     app.connect('autodoc-process-docstring', process_docstring)
     app.connect('autodoc-process-signature', process_signature)

docfx_yaml/monkeypatch.py

@@ -9,6 +9,7 @@
 
 from sphinx.addnodes import desc, desc_signature
 from .utils import transform_node as _transform_node
+from .nodes import remarks
 
 TYPE_SEP_PATTERN = '(\[|\]|, |\(|\))'
 
@@ -322,6 +323,8 @@ def transform_all(self, node):
             data = {}
             name, uid = _get_desc_data(node.parent)
             for child in node:
+                if isinstance(child, remarks):
+                    data['remarks'] = child.astext()
                 if isinstance(child, addnodes.desc):
                     if child.get('desctype') == 'attribute':
                         attribute_map = {} # Used for detecting duplicated attributes in intermediate data and merge them

docfx_yaml/nodes.py

@@ -0,0 +1,20 @@
+# coding: utf-8
+
+"""
+This module is used to add extra supported nodes to sphinx.
+"""
+
+from docutils import nodes
+
+class remarks(nodes.paragraph):
+    """
+    New node for remarks messages.
+    """
+
+    @staticmethod
+    def visit_remarks(self, node):
+        self.visit_paragraph(node)
+
+    @staticmethod
+    def depart_remarks(self, node):
+        self.depart_paragraph(node)

docfx_yaml/writer.py

@@ -25,6 +25,8 @@
 from sphinx import addnodes
 from sphinx.locale import admonitionlabels
 
+from .nodes import remarks
+
 class bcolors:
     HEADER = '\033[95m'
     OKBLUE = '\033[94m'
@@ -1048,5 +1050,9 @@ def visit_substitution_reference(self, node):
     def depart_substitution_reference(self, node):
         pass
 
+    visit_remarks = remarks.visit_remarks
+
+    depart_remarks = remarks.depart_remarks
+
     def unknown_visit(self, node):
         raise NotImplementedError('Unknown node: ' + node.__class__.__name__)

tests/pyexample/example/__init__.py

@@ -0,0 +1,3 @@
+"""
+Docstring from __init__.py
+"""

tests/pyexample/example/example.py

@@ -7,6 +7,8 @@
 class Foo(object):
     """
     A sweet Foo class that does stuff.
+
+    .. remarks:: This is remarks message of class Foo.
     """
 
     class_var = 42  #: Class var docstring
@@ -26,6 +28,9 @@ def method_okay(self, foo=None, bar=None):
         """
         This method should parse okay
 
+        .. remarks:: This is remarks message of method Foo.method_okay.
+            And multiple lines should be supported.
+
         :param str foo: The foo param
         :param str bar: The bar param
         :return: That the method is okay