Add attribute support (via 'annotation' directive) (#97)

This PR adds an 'annotation' directive to our Sphinx integration which
enables documenting attributes. In Sphinx, attributes are an existing
concepts, which refer to what Chapel would call fields. As a result, the
`attr` directive was taken, and `attribute` on top of that seemed
confusing. @lydia-duncan suggested 'annotation' (perhaps in jest), but I
think it's a pretty decent fallback.

Another PR to chpldoc will be necessary to actually emit 'annotation'
directives; it will not be part of this.

Reviewed by @lydia-duncan -- thanks!

sphinxcontrib/chapeldomain/__init__.py

@@ -42,7 +42,8 @@
 chpl_sig_pattern = re.compile(
     r"""^ ((?:\w+\s+)*                             # opt: prefixes
            (?:
-            proc|iter|class|record|interface|operator # must end with keyword
+            proc|iter|class|record|
+            interface|operator|attribute           # must end with keyword
            )\s+
            (?:type\s+|param\s+|ref\s+)?            # opt: 'this' intent
                                                    #  (type, param, ref)
@@ -51,6 +52,7 @@
           \s*?
           (
            (?:[\w$][\w$=]*)|                       # function or method name
+           (?:@[\w$][\w$=\.]*)|                    #  or @attribute name
            (?:[+*/!~%<>=&^|\-:]+)                  #  or operator name
           )  \s*
           (?:\((.*?)\))?                           # opt: arguments
@@ -277,7 +279,8 @@ def _is_proc_like(self):
         return (self.objtype in
                 ('function', 'iterfunction',
                  'method', 'itermethod',
-                 'opfunction', 'opmethod'))
+                 'opfunction', 'opmethod',
+                 'annotation'))
 
     def _get_sig_prefix(self, sig):
         """Return signature prefix text. For attribute, data, and proc/iter
@@ -815,6 +818,7 @@ class ChapelDomain(Domain):
         'module': ObjType(_('module'), 'mod'),
         'opmethod': ObjType(_('opmethod'), 'op'),
         'opfunction': ObjType(_('opfunction'), 'op'),
+        'annotation': ObjType(_('annotation'), 'annotation'),
     }
 
     directives = {
@@ -823,6 +827,7 @@ class ChapelDomain(Domain):
         'function': ChapelModuleLevel,
         'iterfunction': ChapelModuleLevel,
         'opfunction': ChapelModuleLevel,
+        'annotation': ChapelModuleLevel,
 
         'class': ChapelClassObject,
         'record': ChapelClassObject,
@@ -838,6 +843,7 @@ class ChapelDomain(Domain):
     }
 
     roles = {
+        'annotation': ChapelXRefRole(),
         'data': ChapelXRefRole(),
         'const': ChapelXRefRole(),
         'var': ChapelXRefRole(),

test/test_chapeldomain.py

@@ -477,6 +477,10 @@ def test_get_proc_like_prefix__proc(self):
             ('iter foo() ref', 'iter '),
             ('inline iter foo(x, y): int(32)', 'inline iter '),
             ('proc proc proc proc proc proc', 'proc proc proc proc proc '),
+            ('attribute @foo', 'attribute '),
+            ('attribute @foo()', 'attribute '),
+            ('attribute @namespace.foo', 'attribute '),
+            ('attribute @namespace.foo()', 'attribute '),
         ]
         for objtype in ('function', 'method'):
             obj = self.new_obj(objtype)