Changeset 936


Ignore:
Timestamp:
Jun 15, 2012 2:58:34 PM (10 years ago)
Author:
jemian
Message:

refs #8, directives and roles are working at some level, ready to learn how to document SPEC macro source files

Location:
specdomain/src/specdomain
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • specdomain/src/specdomain/sphinxcontrib/specdomain.py

    r935 r936  
    3131non_greedy_filler           = match_all+'?'
    3232double_quote_string_match   = '("'+non_greedy_filler+'")'
    33 word_match                  = '((?:[a-z_][\w]*))'
     33word_match                  = '((?:[a-z_]\w*))'
    3434cdef_match                  = '(cdef)'
    3535
    3636
    3737spec_macro_sig_re = re.compile(
    38     r'''^ ([a-zA-Z_]\w*)         # macro name
    39           ''', re.VERBOSE)
     38                               r'''^ ([a-zA-Z_]\w*)         # macro name
     39                               ''', re.VERBOSE)
    4040
    4141spec_func_sig_re = re.compile(word_match+'\('
    … …  
    4747
    4848
    49 class SpecObject(ObjectDescription):
    50     """
    51     Description of a SPEC object (macro definition or variable).
    52     """
     49class SpecMacroObject(ObjectDescription):
     50    """
     51    Description of a SPEC macro definition
     52    """
     53
     54    doc_field_types = [
     55        TypedField('parameter', label=l_('Parameters'),
     56                   names=('param', 'parameter', 'arg', 'argument',
     57                          'keyword', 'kwarg', 'kwparam'),
     58                   typerolename='def', typenames=('paramtype', 'type'),
     59                   can_collapse=True),
     60        Field('returnvalue', label=l_('Returns'), has_arg=False,
     61              names=('returns', 'return')),
     62        Field('returntype', label=l_('Return type'), has_arg=False,
     63              names=('rtype',)),
     64    ]
    5365
    5466    def add_target_and_index(self, name, sig, signode):
    … …  
    8496        arglist = m.groups()
    8597        name = arglist[0]
    86         args = []
     98        args = ['need to fix this']
    8799        if len(arglist) > 1:
    88100            args = arglist[1:]
    … …  
    101113
    102114
    103 class SpecXRefRole(XRefRole):    # TODO: needs to be checked
     115class SpecVariableObject(ObjectDescription):
     116    """
     117    Description of a SPEC variable
     118    """
     119
     120
     121class SpecXRefRole(XRefRole):
    104122    """ """
    105123   
    106     # TODO: output is not properly formatted yet
    107     # TODO: output does not yet provide link to directive instance
    108 
    109124    def process_link(self, env, refnode, has_explicit_title, title, target):
    110         refnode['spec:def'] = env.temp_data.get('spec:def')
     125        key = ":".join((refnode['refdomain'], refnode['reftype']))
     126        refnode[key] = env.temp_data.get(key)        # key was 'spec:def'
    111127        if not has_explicit_title:
    112128            title = title.lstrip(':')   # only has a meaning for the target
    … …  
    143159    label = 'SPEC, http://www.certif.com'
    144160    object_types = {    # type of object that a domain can document
    145         'def':  ObjType(l_('def'),  'def'),
    146         'rdef': ObjType(l_('rdef'), 'rdef'),
    147         'cdef': ObjType(l_('cdef'), 'cdef'),
     161        'def':    ObjType(l_('def'),    'def'),
     162        'rdef':   ObjType(l_('rdef'),   'rdef'),
     163        'cdef':   ObjType(l_('cdef'),   'cdef'),
     164        'global': ObjType(l_('global'), 'global'),
     165        'local':  ObjType(l_('local'),  'local'),
    148166    }
    149167    directives = {
    150         'def':          SpecObject,
    151         'rdef':         SpecObject,
    152         'cdef':         SpecObject,
     168        'def':          SpecMacroObject,
     169        'rdef':         SpecMacroObject,
     170        'cdef':         SpecMacroObject,
     171        'global':       SpecVariableObject,
     172        'local':        SpecVariableObject,
    153173    }
    154174    roles = {
    155         'def' :  SpecXRefRole(),
    156         'rdef':  SpecXRefRole(),
    157         'cdef':  SpecXRefRole(),
     175        'def' :     SpecXRefRole(),
     176        'rdef':     SpecXRefRole(),
     177        'cdef':     SpecXRefRole(),
     178        'global':   SpecXRefRole(),
     179        'local':    SpecXRefRole(),
    158180    }
    159181    initial_data = {

  • specdomain/src/specdomain/test/test_doc.rst

    r935 r936  
    2222.. spec:def:: def_macro content
    2323
    24    :param str arg: list of arguments is optional
     24   :param arg: list of arguments is optional
     25   :type arg: str
    2526
    2627   This is a standard SPEC macro definition.
    … …  
    4041   :param str cdef_part: name for this part of the chained macro
    4142   :param str flags: see the manual
     43   
     44SPEC cdef macro definitions
     45++++++++++++++++++++++++++++++++
     46
     47.. TODO: pull this subsection once this part is made to work
     48
     49There are several different signatures for SPEC's ``cdef`` macro definition.
     50Here are some examples pulled from the ``SPEC.D`` directory.
     51
     52.. note::  At present, the argument list from ``cdef`` macro definitions
     53   is not being parsed or handled.  This will be fixed in a future revision.
     54   
     55.. literalinclude:: cdef-examples.mac
     56   :linenos:
     57   :language: guess
    4258
    4359SPEC Variables
    4460^^^^^^^^^^^^^^
    4561
    46 * global variable declaration:
    47 * local variable declaration:
     62These are some representative variable declarations in SPEC macro source files::
     63
     64        global  BCDA_GM[]
     65       
     66           global    theta[]
     67           global    2theta[]  # this will not be found
     68           global    _motor[]
     69       
     70        global kohzu_PV kohzuMV_PV UND_PV Und_Off UNDE_TRACK_ON
     71        global       kohzuStop_PV kohzuMode_PV      kohzuMove_PV
     72            global CCD_OVERHEAD_SECS_MEASURED   # measured readout time
     73       
     74            global @A_name[] @B_name[]
     75               unglobal @A_name
     76               unglobal @B_name
     77
     78Variables in Directives
     79+++++++++++++++++++++++
     80
     81global variable declaration:
     82
     83.. spec:global:: A[]
     84
     85   ``A[]`` contains the values of all motors
     86
     87local variable declaration: 
     88
     89.. spec:local:: i
     90
     91   ``i`` is a local loop counter
     92
     93array variable declaration:
     94
     95        tba
     96
     97Variables in Roles
     98+++++++++++++++++++++++
     99
     100* global variable declaration: :spec:global:`A[]`
     101* local variable declaration:  :spec:local:`i`
    48102* array variable declaration:
    49103
    … …  
    55109   :param t: time_t object or None (defaults to ``now()``)
    56110   :type  t: str
    57 
    58 ReST example
    59 ^^^^^^^^^^^^^^
    60 
    61 .. rst:directive:: rst_directive
    62111
    63112

  • specdomain/src/specdomain/test/tester2.py

    r935 r936  
    33#  $Id$
    44
     5
     6"""
     7"""
    58
    69import re
Note: See TracChangeset for help on using the changeset viewer.