Changeset 940

Timestamp:

Jun 17, 2012 1:48:58 PM (11 years ago)

Author:

jemian

Message:

refs #8, making progress, discard code from previous attempt

Location:

specdomain/src/specdomain

Files:

• sphinxcontrib/newer_specdomain.py (deleted)
• sphinxcontrib/specdomain.py (modified) (5 diffs)
• test/test_doc.rst (modified) (3 diffs)

specdomain/src/specdomain/sphinxcontrib/specdomain.py

@@ -12 +12 @@
 # http://sphinx.pocoo.org/ext/appapi.html
 
-import re                                               #@UnusedImport
+import os
+import re
 import string                                           #@UnusedImport
 
@@ -33 +34 @@
 word_match                  = '((?:[a-z_]\w*))'
 cdef_match                  = '(cdef)'
+extended_comment_flag       = '\"\"\"'
 
 
@@ -44 +46 @@
                       re.IGNORECASE|re.DOTALL)
 
-spec_cdef_name_sig_re = re.compile(double_quote_string_match, re.IGNORECASE|re.DOTALL)
+spec_cdef_name_sig_re = re.compile(double_quote_string_match, 
+                                   re.IGNORECASE|re.DOTALL)
+
+
+spec_extended_comment_flag_sig_re = re.compile(extended_comment_flag, 
+                                               re.IGNORECASE|re.DOTALL)
+spec_extended_comment_start_sig_re = re.compile('^'
+                                                + non_greedy_filler
+                                                + extended_comment_flag, 
+                                                re.IGNORECASE|re.DOTALL)
+spec_extended_comment_block_sig_re = re.compile('^'
+                                                + non_greedy_filler
+                                                + extended_comment_flag
+                                                + '(' + non_greedy_filler + ')'
+                                                + extended_comment_flag
+                                                + non_greedy_filler
+                                                + '$', 
+                                                re.IGNORECASE|re.DOTALL|re.MULTILINE)
 
 
@@ -119 +138 @@
 
 
+class SpecMacroSourceObject(ObjectDescription):
+    """
+    Document a SPEC macro source code file
+    
+    This code responds to the ReST file directive::
+    
+        .. spec:macrofile:: partial/path/name/somefile.mac
+            :displayorder: fileorder
+    
+    The ``:displayorder`` parameter indicates how the
+    contents will be sorted for appearance in the ReST document.
+    
+        **fileorder**, **file**
+            Items will be documented in the order in 
+            which they appear in the ``.mac`` file.
+        
+        **alphabetical**, **alpha**
+            Items will be documented in alphabetical order.
+    
+    A (near) future enhancement would be to provide for
+    documenting all macro files in a directory, with optional
+    recursion into subdirectories.  By default, the code would 
+    only document files that match the glob pattern ``*.mac``.
+    Such as::
+    
+       .. spec:directory:: partial/path/name
+          :recursion:
+          :displayorder: alphabetical
+    """
+    
+    # TODO: work-in-progress
+    
+    doc_field_types = [
+        Field('displayorder', label=l_('Display order'), has_arg=False,
+              names=('displayorder', 'synonym')),
+    ]
+
+    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 = sig
+        if indextext:
+            self.indexnode['entries'].append(('single', indextext,
+                                              targetname, ''))
+
+    def handle_signature(self, sig, signode):
+        signode += addnodes.desc_name(sig, sig)
+        # TODO: this is the place to parse the SPEC macro source code file named in "sig"
+        '''
+        Since 2002, SPEC has allowed for triple-quoted strings as extended comments.
+        Few, if any, have used them.
+        Assume that they will contain ReST formatted comments.
+        The first, simplest thing to do is to read the .mac file and only extract
+        all the extended comments and add them as nodes to the current document.
+        
+        An additional step would be to parse for def, cdef, rdef, global, local, const, ...
+        Another step would be to attach source code and provide links from each to
+        highlighted source code blocks.
+        '''
+        results = self.parse_macro_file(sig)
+        indent = ' '*4
+        for item in results:
+            # FIXME:  not desc_annotation but desc_content, but how to get it right?
+            # see <sphinx>/directives/__init__.py for an example
+            # It's a bit more complicated than this.
+            signode += addnodes.desc_annotation('\n', '\n')
+            for line in item.split('\n'):
+                signode += addnodes.desc_annotation(indent+line, indent+line)
+        return sig
+    
+    def parse_macro_file(self, filename):
+        """
+        parse the SPEC macro file and return the ReST blocks
+        
+        :param str filename: name (with optional path) of SPEC macro file
+            (The path is relative to the ``.rst`` document.)
+        :returns [str]: list of ReST-formatted extended comment blocks from SPEC macro file.
+        
+        [future] parse more stuff as planned
+        """
+        results = []
+        if not os.path.exists(filename):
+            raise RuntimeError, "could not find: " + filename
+        
+        buf = open(filename, 'r').read()
+        # TODO: loop until no matches, chopping away the buffer after each match
+        m = spec_extended_comment_block_sig_re.match(buf)
+        if m is not None:
+            rest = m.groups()
+            if len(rest) == 1:
+                results.append(rest[0])
+        return results
+
+
 class SpecXRefRole(XRefRole):
     """ """
@@ -171 +285 @@
         'global':       SpecVariableObject,
         'local':        SpecVariableObject,
+        'macrofile':    SpecMacroSourceObject,
     }
     roles = {

specdomain/src/specdomain/test/test_doc.rst

@@ -101 +101 @@
 * local variable declaration:  :spec:local:`i`
 * array variable declaration: 
+* constant declaration:
 
 Python example
@@ -129 +130 @@
 ^^^^^^^^^^^^^^
 
-* global variable declaration: 
-* local variable declaration: 
+The SPEC macro language provides for several types of variable:
+
+* global variables, such as:  :spec:global:`A[]`
+* local variable, such as:  :spec:local:`i`
 * array variable declaration: 
+* constant declaration:
+
+Source code documentation
+============================
 
 Python example
@@ -137 +144 @@
 
 See the python method :py:func:`python_function()` (defined above)
+
+..  This should document the Python module supporting the specdomain
+
+:class:`SpecVariableObject` (Python Module)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: sphinxcontrib.specdomain.SpecVariableObject
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: sphinxcontrib.specdomain
+    :members:
+
+
+
+SPEC macro source file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. spec:macrofile:: cdef-examples.mac