Changeset 940


Ignore:
Timestamp:
Jun 17, 2012 1:48:58 PM (10 years ago)
Author:
jemian
Message:

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

Location:
specdomain/src/specdomain
Files:
1 deleted
2 edited

Legend:

Unmodified
Added
Removed
  • specdomain/src/specdomain/sphinxcontrib/specdomain.py

    r937 r940  
    1212# http://sphinx.pocoo.org/ext/appapi.html
    1313
    14 import re                                               #@UnusedImport
     14import os
     15import re
    1516import string                                           #@UnusedImport
    1617
     
    3334word_match                  = '((?:[a-z_]\w*))'
    3435cdef_match                  = '(cdef)'
     36extended_comment_flag       = '\"\"\"'
    3537
    3638
     
    4446                      re.IGNORECASE|re.DOTALL)
    4547
    46 spec_cdef_name_sig_re = re.compile(double_quote_string_match, re.IGNORECASE|re.DOTALL)
     48spec_cdef_name_sig_re = re.compile(double_quote_string_match,
     49                                   re.IGNORECASE|re.DOTALL)
     50
     51
     52spec_extended_comment_flag_sig_re = re.compile(extended_comment_flag,
     53                                               re.IGNORECASE|re.DOTALL)
     54spec_extended_comment_start_sig_re = re.compile('^'
     55                                                + non_greedy_filler
     56                                                + extended_comment_flag,
     57                                                re.IGNORECASE|re.DOTALL)
     58spec_extended_comment_block_sig_re = re.compile('^'
     59                                                + non_greedy_filler
     60                                                + extended_comment_flag
     61                                                + '(' + non_greedy_filler + ')'
     62                                                + extended_comment_flag
     63                                                + non_greedy_filler
     64                                                + '$',
     65                                                re.IGNORECASE|re.DOTALL|re.MULTILINE)
    4766
    4867
     
    119138
    120139
     140class SpecMacroSourceObject(ObjectDescription):
     141    """
     142    Document a SPEC macro source code file
     143   
     144    This code responds to the ReST file directive::
     145   
     146        .. spec:macrofile:: partial/path/name/somefile.mac
     147            :displayorder: fileorder
     148   
     149    The ``:displayorder`` parameter indicates how the
     150    contents will be sorted for appearance in the ReST document.
     151   
     152        **fileorder**, **file**
     153            Items will be documented in the order in
     154            which they appear in the ``.mac`` file.
     155       
     156        **alphabetical**, **alpha**
     157            Items will be documented in alphabetical order.
     158   
     159    A (near) future enhancement would be to provide for
     160    documenting all macro files in a directory, with optional
     161    recursion into subdirectories.  By default, the code would
     162    only document files that match the glob pattern ``*.mac``.
     163    Such as::
     164   
     165       .. spec:directory:: partial/path/name
     166          :recursion:
     167          :displayorder: alphabetical
     168    """
     169   
     170    # TODO: work-in-progress
     171   
     172    doc_field_types = [
     173        Field('displayorder', label=l_('Display order'), has_arg=False,
     174              names=('displayorder', 'synonym')),
     175    ]
     176
     177    def add_target_and_index(self, name, sig, signode):
     178        targetname = '%s-%s' % (self.objtype, name)
     179        signode['ids'].append(targetname)
     180        self.state.document.note_explicit_target(signode)
     181        indextext = sig
     182        if indextext:
     183            self.indexnode['entries'].append(('single', indextext,
     184                                              targetname, ''))
     185
     186    def handle_signature(self, sig, signode):
     187        signode += addnodes.desc_name(sig, sig)
     188        # TODO: this is the place to parse the SPEC macro source code file named in "sig"
     189        '''
     190        Since 2002, SPEC has allowed for triple-quoted strings as extended comments.
     191        Few, if any, have used them.
     192        Assume that they will contain ReST formatted comments.
     193        The first, simplest thing to do is to read the .mac file and only extract
     194        all the extended comments and add them as nodes to the current document.
     195       
     196        An additional step would be to parse for def, cdef, rdef, global, local, const, ...
     197        Another step would be to attach source code and provide links from each to
     198        highlighted source code blocks.
     199        '''
     200        results = self.parse_macro_file(sig)
     201        indent = ' '*4
     202        for item in results:
     203            # FIXME:  not desc_annotation but desc_content, but how to get it right?
     204            # see <sphinx>/directives/__init__.py for an example
     205            # It's a bit more complicated than this.
     206            signode += addnodes.desc_annotation('\n', '\n')
     207            for line in item.split('\n'):
     208                signode += addnodes.desc_annotation(indent+line, indent+line)
     209        return sig
     210   
     211    def parse_macro_file(self, filename):
     212        """
     213        parse the SPEC macro file and return the ReST blocks
     214       
     215        :param str filename: name (with optional path) of SPEC macro file
     216            (The path is relative to the ``.rst`` document.)
     217        :returns [str]: list of ReST-formatted extended comment blocks from SPEC macro file.
     218       
     219        [future] parse more stuff as planned
     220        """
     221        results = []
     222        if not os.path.exists(filename):
     223            raise RuntimeError, "could not find: " + filename
     224       
     225        buf = open(filename, 'r').read()
     226        # TODO: loop until no matches, chopping away the buffer after each match
     227        m = spec_extended_comment_block_sig_re.match(buf)
     228        if m is not None:
     229            rest = m.groups()
     230            if len(rest) == 1:
     231                results.append(rest[0])
     232        return results
     233
     234
    121235class SpecXRefRole(XRefRole):
    122236    """ """
     
    171285        'global':       SpecVariableObject,
    172286        'local':        SpecVariableObject,
     287        'macrofile':    SpecMacroSourceObject,
    173288    }
    174289    roles = {
  • specdomain/src/specdomain/test/test_doc.rst

    r936 r940  
    101101* local variable declaration:  :spec:local:`i`
    102102* array variable declaration:
     103* constant declaration:
    103104
    104105Python example
     
    129130^^^^^^^^^^^^^^
    130131
    131 * global variable declaration:
    132 * local variable declaration:
     132The SPEC macro language provides for several types of variable:
     133
     134* global variables, such as:  :spec:global:`A[]`
     135* local variable, such as:  :spec:local:`i`
    133136* array variable declaration:
     137* constant declaration:
     138
     139Source code documentation
     140============================
    134141
    135142Python example
     
    137144
    138145See the python method :py:func:`python_function()` (defined above)
     146
     147..  This should document the Python module supporting the specdomain
     148
     149:class:`SpecVariableObject` (Python Module)
     150^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     151
     152.. autoclass:: sphinxcontrib.specdomain.SpecVariableObject
     153    :members:
     154    :undoc-members:
     155    :show-inheritance:
     156
     157.. automodule:: sphinxcontrib.specdomain
     158    :members:
     159
     160
     161
     162SPEC macro source file
     163^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     164
     165.. spec:macrofile:: cdef-examples.mac
Note: See TracChangeset for help on using the changeset viewer.