Changeset 930

Timestamp:

Jun 14, 2012 1:12:01 PM (11 years ago)

Author:

jemian

Message:

refs #8, progress on adding directives to the index

Location:

specdomain/src

Files:

• round2/sphinxcontrib/tester.py (modified) (1 diff)
• specdomain/sphinxcontrib/specdomain.py (modified) (4 diffs)
• specdomain/test/test_doc.rst (modified) (3 diffs)

specdomain/src/round2/sphinxcontrib/tester.py

@@ -32 +32 @@
         name, args, last = m.groups()
         print name, args.strip().split()
+
+spec_macro_sig_re = re.compile(
+    r'''^ ([a-zA-Z_]\w*)         # macro name
+          ''', re.VERBOSE)
+
+sig = u'cdef(macro_name, content, groupname, flags)'
+m = spec_macro_sig_re.match(sig)
+print m.groups()
+print args
+

specdomain/src/specdomain/sphinxcontrib/specdomain.py

@@ -28 +28 @@
 
 
+spec_macro_sig_re = re.compile(
+    r'''^ ([a-zA-Z_]\w*)         # macro name
+          ''', re.VERBOSE)
+
+
 class SpecObject(ObjectDescription):
     """
@@ -33 +38 @@
     """
 
+    def add_target_and_index(self, name, sig, signode):
+        targetname = '%s-%s' % (self.objtype, name)
+        signode['ids'].append(targetname)
+        self.state.document.note_explicit_target(signode)
+        indextext = self._get_index_text(name)
+        if indextext:
+            self.indexnode['entries'].append(('single', indextext,
+                                              targetname, ''))
+
+    def _get_index_text(self, name):
+        macro_types = {
+            'def':  '%s (SPEC macro)',
+            'rdef': '%s (SPEC run-time macro)',
+            'cdef': '%s (SPEC chained macro)',
+        }
+        if self.objtype in macro_types:
+            return _(macro_types[self.objtype]) % name
+        else:
+            return ''
+
     def handle_signature(self, sig, signode):
-        # TODO: must be able to match these
-        # def macro_name
-        # def macro_name()
-        # def macro_name(arg1, arg2)
-        name, args = sig.strip().split()    
+        # Must be able to match these (without preceding def or rdef)
+        #     def macro_name
+        #     def macro_name()
+        #     def macro_name(arg1, arg2)
+        #     rdef macro_name
+        #     cdef(macro_name, content, groupname, flags)
+        m = spec_macro_sig_re.match(sig)
+        if m is None:
+            raise ValueError
+        arglist = sig.strip().split()
+        if len(arglist) == 0:
+            raise ValueError
+        if sig.startswith('cdef'):
+            special = sig.lstrip('cdef')
+        name = arglist[0]
         signode += addnodes.desc_name(name, name)
+        if len(arglist) > 1:
+            args = sig.lstrip(name).strip()
         if len(args) > 0:
             signode += addnodes.desc_addname(args, args)
         return name
 
-    def _get_index_text(self, name):    # TODO: needs to be checked
-        if self.objtype == 'def':
-            return _('%s (SPEC macro)') % name
-        elif self.objtype == 'rdef':
-            return _('%s (SPEC macro)') % name
-        elif self.objtype == 'cdef':
-            return _('%s (SPEC global)') % name
-        else:
-            return ''
-
 
 class SpecXRefRole(XRefRole):    # TODO: needs to be checked
+    """ """
+    
+    # TODO: output is not properly formatted yet
+    # TODO: output does not yet provide link to directive instance
 
     def process_link(self, env, refnode, has_explicit_title, title, target):
@@ -72 +103 @@
 
     def result_nodes(self, document, env, node, is_ref):
+        # this code adds index entries for each role instance
         if not is_ref:
             return [node], []
@@ -88 +120 @@
 class SpecDomain(Domain):
     """SPEC language domain."""
+    
     name = 'spec'
     label = 'SPEC, http://www.certif.com'

specdomain/src/specdomain/test/test_doc.rst

@@ -20 +20 @@
 ^^^^^^^^^^^
 
-.. spec:def:: no_args_macro
+.. spec:def:: def_macro content
 
-.. spec:def:: def_macro arg1 arg2 arg3
+   :param str arg: list of arguments is optional
 
-   :param arg1: anything
-   :type  arg1: str
-   :param arg2: another thing
+   This is a standard SPEC macro definition.
 
 .. spec:rdef:: rdef_macro content
 
-   :param content: SPEC code (single or multi-line but typically a single macro)
-   :type  content: str
+   This is a SPEC macro definition with symbols that are evaluated only at run-time.
 
-.. spec:cdef:: cdef_macro(identifier, content, placement)
+.. spec:cdef:: cdef(macro_name, [content, groupname, [flags]])
 
-   :param identifier: one-word name for this macro chain
-   :type  identifier: str
-   :param content: SPEC code to be inserted (typically a single macro)
-   :type  content: str
-   :param placement: see the manual
-   :type  placement: str
+   :param str macro_name: one-word name (quoted string) for this macro chain
+   :param str content: SPEC code to be inserted (typically a single macro)
+   :param str groupname: name of organizational group
+   :param str flags: see the manual
 
 SPEC Variables
@@ -67 +62 @@
 
 A *role* refers to a *directive* (makes a link to a *directive* defined elsewhere).
-Each of these items should produce a valid link.
+Each of these items should produce a valid link.  Additionally, every call to a 
+*role* should produce an index entry.
 
 SPEC Macros
@@ -74 +70 @@
 * macro definition: :spec:def:`def_macro`
 * runtime-defined macro definition: :spec:rdef:`rdef_macro`
-* chained macro definition: :spec:cdef:`cdef_macro`
+* chained macro definition: :spec:cdef:`cdef(macro_name, content, groupname, flags)`
 
 SPEC Variables