Changeset 1007 for specdomain/trunk


Ignore:
Timestamp:
Jul 12, 2012 5:56:32 PM (11 years ago)
Author:
jemian
Message:

refs #8, much, MUCH better reporting, almost ready for release, need to improve the "howto" documentation in the docs/ subdir

Location:
specdomain/trunk/src/specdomain
Files:
13 added
7 edited

Legend:

Unmodified
Added
Removed

  • specdomain/trunk/src/specdomain/CHANGES

    r998 r1007  
    33This file describes user-visible changes between the extension versions.
    44
    5 Version 1.0 (2012-07-01)
     5Version 1.0 (2012-07-13)
    66------------------------
    77
    8 * Initial version.
     8* Initial release.

  • specdomain/trunk/src/specdomain/doc/index.rst

    r995 r1007  
    1010.. include:: ../README
    1111
    12 Contents:
     12Contents
     13==================
     14
     15.. toctree::
     16   :maxdepth: 2
     17
     18   howto
     19   conventions
     20   spec
     21   example
     22   bpm
     23   aalength
     24
     25Other matters
     26==================
    1327
    1428.. toctree::
    … …  
    1630
    1731   objectives
    18    spec
    19 
    20 Other matters:
    21 
    22 .. toctree::
    23    :maxdepth: 2
    24 
     32   todo
     33   bugs
    2534   changes
    2635   license

  • specdomain/trunk/src/specdomain/doc/spec.rst

    r995 r1007  
    263263
    264264
    265 Common Conventions
    266 ====================
    267 
    268 There are several conventions to help provide consistency.
    269 These are not requirements.
    270 
    271 extended comments
    272 -----------------
    273 
    274 Only the first extended comment in a "section" should be documented.
    275 (This setting could be changed with an optional switch.)
    276 
    277 A "section" might be the global scope of a .mac file or a macro definition block.
    278 
    279 As much as possible, use the python documentation style (that is,
    280 first comment is module documentation, first comment inside
    281 macro definition is the macro documentation).
    282 
    283 hidden objects
    284 ----------------
    285 
    286 *Hidden* objects begin with at least one underline character,
    287 such as ``_hidden``.  This includes macros and variables.
    288 These should be optional in the documentation.
    289 
    290 *Anonymous* objects begin with at least two underline characters,
    291 such as ``___anon``.  This includes macros and variables.
    292 These should not be documented unless specifically requested and
    293 only then if hidden objects are documented.
    294 
    295 undeclared variables
    296 ---------------------
    297 
    298 Undeclared variables (those with no formal global, local, constant,
    299 or array declaration) will not be documented.  At least for now.
    300 
    301 parameter descriptions
    302 ----------------------------
    303 
    304 Use the same syntax as parameter declarations for Python modules. 
    305 Here is an example SPEC macro with reST markup::
    306 
    307         def my_comment '{
    308             '''
    309             Make a comment
    310            
    311             usage: ``my_comment "AR aligned to 15.14063 degrees"``
    312            
    313             :param str text: message to be printed
    314             '''
    315             qcomment "%s" $1
    316         }'
    317 
    318 which documentation looks like this:
    319 
    320 .. spec:def:: my_comment text
    321            
    322             Make a comment
    323            
    324             usage: ``my_comment "AR aligned to 15.14063 degrees"``
    325            
    326             :param str text: message to be printed
    327265
    328266------------

  • specdomain/trunk/src/specdomain/doc/starter.py

    r995 r1007  
    77(and provides a way to use the source-code debugger for the process)
    88'''
    9 
    10 import os
    11 import sphinx
    12 import sys
    139
    1410import os

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

    r994 r1007  
    1919import os
    2020import re
    21 import string                                           #@UnusedImport
    22 import sys                                              #@UnusedImport
    23 
    24 from docutils import nodes                              #@UnusedImport
    25 from docutils.parsers.rst import directives             #@UnusedImport
     21
     22from docutils import nodes
    2623
    2724from sphinx import addnodes
    2825from sphinx.roles import XRefRole
    29 from sphinx.locale import l_, _                         #@UnusedImport
     26from sphinx.locale import l_, _
    3027from sphinx.directives import ObjectDescription
    31 from sphinx.domains import Domain, ObjType, Index       #@UnusedImport
    32 from sphinx.util.compat import Directive                #@UnusedImport
    33 from sphinx.util.nodes import make_refnode, nested_parse_with_titles    #@UnusedImport
     28from sphinx.domains import Domain, ObjType
     29from sphinx.util.nodes import make_refnode
    3430from sphinx.util.docfields import Field, TypedField
    35 from sphinx.util.docstrings import prepare_docstring    #@UnusedImport
    36 
    37 #from docutils.statemachine import ViewList, string2lines
    38 #import sphinx.util.nodes
     31from sphinx.util.docstrings import prepare_docstring
     32
    3933from sphinx.ext.autodoc import Documenter, bool_option
    40 #from sphinx.util.inspect import getargspec, isdescriptor, safe_getmembers, \
    41 #     safe_getattr, safe_repr
    42 #from sphinx.util.pycompat import base_exception, class_types
    4334from specmacrofileparser import SpecMacrofileParser
    44 from docutils.statemachine import ViewList    #@UnusedImport
    4535
    4636
    … …  
    8171            Items will be documented in the order in
    8272            which they appear in the ``.mac`` file.
     73            (Default)
    8374       
    8475        **alphabetical** or **alpha**
    8576            Items will be documented in alphabetical order.
     77            (Not implemented at present.)
    8678   
    8779    .. tip::
    … …  
    174166
    175167class SpecDirDocumenter(Documenter):
     168    """
     169    Document a directory containing SPEC macro source code files.
     170   
     171    This code responds to the ReST file directive::
     172   
     173        .. autospecdir:: partial/path/name
     174    """
    176175    objtype = 'specdir'
    177176    member_order = 50
    … …  
    189188    def generate(self, *args, **kw):
    190189        """
    191         Look at the named directory and
    192         Generate reST for the object given by *self.name*, and possibly for
    193         its members.
     190        Look at the named directory and generate reST for the
     191        object given by *self.name*, and possibly for its members.
    194192        """
    195193        # now, parse the .mac files in the SPEC directory

  • specdomain/trunk/src/specdomain/sphinxcontrib/specmacrofileparser.py

    r1004 r1007  
    2121import os
    2222import re
    23 from pprint import pprint
     23from pprint import pprint        #@UnusedImport
    2424
    2525#   http://www.txt2re.com/index-python.php3
    … …  
    173173        Figure out what can be documented in the file's contents (in self.buf)
    174174       
    175             each of the list_...() methods returns a
     175            each of the list_something() methods returns a
    176176            list of dictionaries where each dictionary
    177177            has the keys: objtype, start_line, end_line, and others
    … …  
    192192       
    193193        # then, the analysis of what was found
     194        # proceed line-by-line in order
     195        # TODO: could override this rule with an option
    194196        self.findings = []
    195197        description = ''
    … …  
    217219                    # TODO: could override this rule with an option
    218220                    self.findings.append(item)
     221                item['summary'] = self._extract_summary(item.get('description', ''))
    219222           
    220223            if item['objtype'] == 'extended comment':
    … …  
    233236                    if len(description)>0:
    234237                        item['description'] = description
     238                        item['summary'] = self._extract_summary(description)
    235239                        clear_description = True
    236240                    if not item['name'].startswith('_'):
    … …  
    240244            if clear_description:
    241245                description, clear_description = '', False
     246   
     247    def _extract_summary(self, description):
     248        """
     249        return the short summary line from the item description text
     250       
     251        The summary line is the first line in the docstring,
     252        such as the line above.
     253       
     254        For our purposes now, we return the first paragraph,
     255        if it is not a parameter block such as ``:param var: ...``.
     256        """
     257        if len(description) == 0:
     258            return ''
     259        text = []
     260        for line in description.strip().splitlines():
     261            if len(line.strip()) == 0:
     262                break
     263            if not line.strip().startswith(':'):
     264                text.append(line)
     265        return ' '.join(text)
    242266
    243267    def list_extended_comments(self):
    … …  
    311335            if content.find('[') >= 0:
    312336                content = re.sub('\s*?\[', '[', content)    # remove blank space before [
    313             for var in variable_name_re.finditer(content):
    314                 name = var.group(1)
    315                 if len(name) > 0:
    316                     items.append({
    317                                     'start_line': start,
    318                                     'end_line':   end,
    319                                     'objtype':    objtype,
    320                                     'name':       name,
    321                                     'parent':     None,
    322                                   })
     337            if objtype in ('constant'):
     338                name = content.strip().split()[0]
     339                items.append({
     340                                'start_line': start,
     341                                'end_line':   end,
     342                                'objtype':    objtype,
     343                                'name':       name,
     344                                'parent':     None,
     345                              })
     346            else:
     347                for var in variable_name_re.finditer(content):
     348                    name = var.group(1)
     349                    if len(name) > 0:
     350                        items.append({
     351                                        'start_line': start,
     352                                        'end_line':   end,
     353                                        'objtype':    objtype,
     354                                        'name':       name,
     355                                        'parent':     None,
     356                                      })
    323357        return items
    324358
    … …  
    427461                s.append( '' )
    428462                s.append(r['text'])
     463                s.append( '' )
    429464            elif r['objtype'] in ('def', 'rdef', 'cdef', ):
    430465                # TODO: apply rules to suppress reporting under certain circumstances
    … …  
    437472                                              r['end_line']) )
    438473                s.append( '.. spec:%s:: %s' % ( r['objtype'], r['name'],) )
     474                s.append('')
     475                s.append(' '*4 + '*' + r['objtype'] + ' macro declaration*')
    439476                desc = r.get('description', '')
    440477                if len(desc) > 0:
    … …  
    442479                    for line in desc.splitlines():
    443480                        s.append(' '*4 + line)
     481                s.append( '' )
    444482            elif r['objtype'] in ('function def', 'function rdef',):
    445483                # TODO: apply rules to suppress reporting under certain circumstances
    … …  
    453491                                              r['end_line']) )
    454492                s.append( '.. spec:%s:: %s(%s)' % ( objtype, r['name'], r['args']) )
     493                s.append('')
     494                s.append(' '*4 + '*' + r['objtype'].split()[1] + '() macro function declaration*')
    455495                desc = r.get('description', '')
    456496                if len(desc) > 0:
    … …  
    458498                    for line in desc.splitlines():
    459499                        s.append(' '*4 + line)
    460             elif r['objtype'] in ('local', 'global', 'constant'):
     500                s.append( '' )
     501           
     502            # Why document local variables in a global scope?
     503            elif r['objtype'] in ('global', 'constant'):
    461504                # TODO: apply rules to suppress reporting under certain circumstances
    462505                declarations.append(r)
    463                 s.append( '.. spec:%s:: %s' % ( r['objtype'], r['name']) )
    464                 desc = r.get('description', '')
    465                 if len(desc) > 0:
     506                if r.get('parent') is None:
     507                    s.append( '.. spec:%s:: %s' % ( r['objtype'], r['name']) )
    466508                    s.append('')
    467                     for line in desc.splitlines():
    468                         s.append(' '*4 + line)
     509                    if r['objtype'] in ('constant'):
     510                        s.append(' '*4 + '*constant declaration*')
     511                    else:
     512                        s.append(' '*4 + '*' + r['objtype'] + ' variable declaration*')
     513                    desc = r.get('description', '')
     514                    if len(desc) > 0:
     515                        s.append('')
     516                        for line in desc.splitlines():
     517                            s.append(' '*4 + line)
     518                    s.append( '' )
    469519
    470520        s += _report_table('Variable Declarations (%s)' % self.filename, declarations,
    471                           ('objtype', 'name', 'start_line',))
     521                          ('objtype', 'name', 'start_line', 'summary', ))
    472522        s += _report_table('Macro Declarations (%s)' % self.filename, macros,
    473                           ('objtype', 'name', 'start_line', 'end_line'))
     523                          ('objtype', 'name', 'start_line', 'end_line', 'summary', ))
    474524        s += _report_table('Function Macro Declarations (%s)' % self.filename, functions,
    475                           ('objtype', 'name', 'start_line', 'end_line', 'args'))
    476         #s += _report_table('Findings from .mac File', self.findings, ('start_line', 'objtype', 'line',))
     525                          ('objtype', 'name', 'start_line', 'end_line', 'args', 'summary', ))
     526        #s += _report_table('Findings from .mac File', self.findings, ('start_line', 'objtype', 'line', 'summary', ))
    477527
    478528        return '\n'.join(s)
    … …  
    494544    for d in itemlist:
    495545        if d['start_line'] != last_line:
    496             rows.append( tuple([str(d[key]).strip() for key in col_keys]) )
     546            rowdata = [str(d.get(key,'')).strip() for key in col_keys]
     547            rows.append( tuple(rowdata) )
    497548        last_line = d['start_line']
    498549    return make_rest_table(title, col_keys, rows, '=')
    … …  
    508559    :param str titlechar: character to use when underlining title as reST section heading
    509560    :returns [str]: each list item is reST
    510    
    511     Example::
    512 
    513         title = 'This is a reST table'
    514         labels = ('name', 'phone', 'email')
    515         rows = [
    516                 ['Snoopy',           '12345', 'dog@house'],
    517                 ['Red Baron',        '65432', 'fokker@triplane'],
    518                 ['Charlie Brown',    '12345', 'main@house'],
    519                 ]
    520         print '\n'.join(make_rest_table(title, labels, rows))
    521    
    522     This results in this reST::
    523    
    524         This is a reST table
    525         ====================
    526        
    527         ============= ===== ===============
    528         name          phone email         
    529         ============= ===== ===============
    530         Snoopy        12345 dog@house     
    531         Red Baron     65432 fokker@triplane
    532         Charlie Brown 12345 main@house     
    533         ============= ===== ===============
    534561    """
     562    # this is commented out since it causes a warning when building:
     563    #  specmacrofileparser.py:docstring of sphinxcontrib.specmacrofileparser.make_rest_table:14: WARNING: Block quote ends without a blank line; unexpected unindent.
     564    # -----
     565    #    """
     566    #    build a reST table
     567    #       
     568    #    :param str title: placed in a section heading above the table
     569    #    :param [str] labels: columns labels
     570    #    :param [[str]] rows: 2-D grid of data, len(labels) == len(data[i]) for all i
     571    #    :param str titlechar: character to use when underlining title as reST section heading
     572    #    :returns [str]: each list item is reST
     573    #
     574    #    Example::
     575    #       
     576    #        title = 'This is a reST table'
     577    #        labels = ('name', 'phone', 'email')
     578    #        rows = [
     579    #                ['Snoopy',           '12345', 'dog@house'],
     580    #                ['Red Baron',        '65432', 'fokker@triplane'],
     581    #                ['Charlie Brown',    '12345', 'main@house'],
     582    #        ]
     583    #        print '\n'.join(make_rest_table(title, labels, rows, titlechar='~'))
     584    #
     585    #    This results in this reST::
     586    #   
     587    #        This is a reST table
     588    #        ~~~~~~~~~~~~~~~~~~~~
     589    #       
     590    #        ============= ===== ===============
     591    #        name          phone email         
     592    #        ============= ===== ===============
     593    #        Snoopy        12345 dog@house     
     594    #        Red Baron     65432 fokker@triplane
     595    #        Charlie Brown 12345 main@house     
     596    #        ============= ===== ===============
     597    #   
     598    #    """
    535599    s = []
    536600    if len(rows) == 0:

  • specdomain/trunk/src/specdomain/test/test_autospecdir.rst

    r994 r1007  
    22
    33.. autospecdir:: ../macros/
     4
     5.. end
Note: See TracChangeset for help on using the changeset viewer.