Changeset 1007

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:

• CHANGES (modified) (1 diff)
• doc/aalength.mac (added)
• doc/aalength.rst (added)
• doc/bpm.mac (added)
• doc/bpm.rst (added)
• doc/bugs.rst (added)
• doc/conventions.rst (added)
• doc/example.mac (added)
• doc/example.rst (added)
• doc/howto-build.rst (added)
• doc/howto-configure.rst (added)
• doc/howto-install.rst (added)
• doc/howto.rst (added)
• doc/index.rst (modified) (2 diffs)
• doc/spec.rst (modified) (1 diff)
• doc/starter.py (modified) (1 diff)
• doc/todo.rst (added)
• sphinxcontrib/specdomain.py (modified) (4 diffs)
• sphinxcontrib/specmacrofileparser.py (modified) (14 diffs)
• test/test_autospecdir.rst (modified) (1 diff)

specdomain/trunk/src/specdomain/CHANGES

@@ -3 +3 @@
 This file describes user-visible changes between the extension versions.
 
-Version 1.0 (2012-07-01)
+Version 1.0 (2012-07-13)
 ------------------------
 
-* Initial version.
+* Initial release.

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

@@ -10 +10 @@
 .. include:: ../README
 
-Contents:
+Contents
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   howto
+   conventions
+   spec
+   example
+   bpm
+   aalength
+
+Other matters
+==================
 
 .. toctree::
@@ -16 +30 @@
 
    objectives
-   spec
-
-Other matters:
-
-.. toctree::
-   :maxdepth: 2
-
+   todo
+   bugs
    changes
    license

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

@@ -263 +263 @@
 
 
-Common Conventions
-====================
-
-There are several conventions to help provide consistency.
-These are not requirements.
-
-extended comments
------------------
-
-Only the first extended comment in a "section" should be documented.
-(This setting could be changed with an optional switch.)
-
-A "section" might be the global scope of a .mac file or a macro definition block.
-
-As much as possible, use the python documentation style (that is, 
-first comment is module documentation, first comment inside 
-macro definition is the macro documentation).
-
-hidden objects
-----------------
-
-*Hidden* objects begin with at least one underline character, 
-such as ``_hidden``.  This includes macros and variables.
-These should be optional in the documentation.
-
-*Anonymous* objects begin with at least two underline characters,
-such as ``___anon``.  This includes macros and variables.
-These should not be documented unless specifically requested and 
-only then if hidden objects are documented. 
-
-undeclared variables
----------------------
-
-Undeclared variables (those with no formal global, local, constant, 
-or array declaration) will not be documented.  At least for now.
-
-parameter descriptions
-----------------------------
-
-Use the same syntax as parameter declarations for Python modules.  
-Here is an example SPEC macro with reST markup::
-
-        def my_comment '{
-            '''
-            Make a comment
-            
-            usage: ``my_comment "AR aligned to 15.14063 degrees"``
-            
-            :param str text: message to be printed
-            '''
-            qcomment "%s" $1
-        }'
-
-which documentation looks like this:
-
-.. spec:def:: my_comment text
-            
-            Make a comment
-            
-            usage: ``my_comment "AR aligned to 15.14063 degrees"``
-            
-            :param str text: message to be printed
 
 ------------

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

@@ -7 +7 @@
 (and provides a way to use the source-code debugger for the process)
 '''
-
-import os
-import sphinx
-import sys
 
 import os

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

@@ -19 +19 @@
 import os
 import re
-import string                                           #@UnusedImport
-import sys                                              #@UnusedImport
-
-from docutils import nodes                              #@UnusedImport
-from docutils.parsers.rst import directives             #@UnusedImport
+
+from docutils import nodes
 
 from sphinx import addnodes
 from sphinx.roles import XRefRole
-from sphinx.locale import l_, _                         #@UnusedImport
+from sphinx.locale import l_, _
 from sphinx.directives import ObjectDescription
-from sphinx.domains import Domain, ObjType, Index       #@UnusedImport
-from sphinx.util.compat import Directive                #@UnusedImport
-from sphinx.util.nodes import make_refnode, nested_parse_with_titles    #@UnusedImport
+from sphinx.domains import Domain, ObjType
+from sphinx.util.nodes import make_refnode
 from sphinx.util.docfields import Field, TypedField
-from sphinx.util.docstrings import prepare_docstring    #@UnusedImport
-
-#from docutils.statemachine import ViewList, string2lines
-#import sphinx.util.nodes
+from sphinx.util.docstrings import prepare_docstring
+
 from sphinx.ext.autodoc import Documenter, bool_option
-#from sphinx.util.inspect import getargspec, isdescriptor, safe_getmembers, \
-#     safe_getattr, safe_repr
-#from sphinx.util.pycompat import base_exception, class_types
 from specmacrofileparser import SpecMacrofileParser
-from docutils.statemachine import ViewList    #@UnusedImport
 
 
@@ -81 +71 @@
             Items will be documented in the order in 
             which they appear in the ``.mac`` file.
+            (Default)
         
         **alphabetical** or **alpha**
             Items will be documented in alphabetical order.
+            (Not implemented at present.)
     
     .. tip::
@@ -174 +166 @@
 
 class SpecDirDocumenter(Documenter):
+    """
+    Document a directory containing SPEC macro source code files.
+    
+    This code responds to the ReST file directive::
+    
+        .. autospecdir:: partial/path/name
+    """
     objtype = 'specdir'
     member_order = 50
@@ -189 +188 @@
     def generate(self, *args, **kw):
         """
-        Look at the named directory and
-        Generate reST for the object given by *self.name*, and possibly for
-        its members.
+        Look at the named directory and generate reST for the 
+        object given by *self.name*, and possibly for its members.
         """
         # now, parse the .mac files in the SPEC directory

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

@@ -21 +21 @@
 import os
 import re
-from pprint import pprint
+from pprint import pprint        #@UnusedImport
 
 #   http://www.txt2re.com/index-python.php3
@@ -173 +173 @@
         Figure out what can be documented in the file's contents (in self.buf)
         
-            each of the list_...() methods returns a 
+            each of the list_something() methods returns a 
             list of dictionaries where each dictionary 
             has the keys: objtype, start_line, end_line, and others
@@ -192 +192 @@
         
         # then, the analysis of what was found
+        # proceed line-by-line in order
+        # TODO: could override this rule with an option
         self.findings = []
         description = ''
@@ -217 +219 @@
                     # TODO: could override this rule with an option
                     self.findings.append(item)
+                item['summary'] = self._extract_summary(item.get('description', ''))
             
             if item['objtype'] == 'extended comment':
@@ -233 +236 @@
                     if len(description)>0:
                         item['description'] = description
+                        item['summary'] = self._extract_summary(description)
                         clear_description = True
                     if not item['name'].startswith('_'):
@@ -240 +244 @@
             if clear_description:
                 description, clear_description = '', False
+    
+    def _extract_summary(self, description):
+        """
+        return the short summary line from the item description text
+        
+        The summary line is the first line in the docstring,
+        such as the line above.
+        
+        For our purposes now, we return the first paragraph, 
+        if it is not a parameter block such as ``:param var: ...``.
+        """
+        if len(description) == 0:
+            return ''
+        text = []
+        for line in description.strip().splitlines():
+            if len(line.strip()) == 0:
+                break
+            if not line.strip().startswith(':'):
+                text.append(line)
+        return ' '.join(text)
 
     def list_extended_comments(self):
@@ -311 +335 @@
             if content.find('[') >= 0:
                 content = re.sub('\s*?\[', '[', content)    # remove blank space before [
-            for var in variable_name_re.finditer(content):
-                name = var.group(1)
-                if len(name) > 0:
-                    items.append({
-                                    'start_line': start, 
-                                    'end_line':   end, 
-                                    'objtype':    objtype,
-                                    'name':       name,
-                                    'parent':     None,
-                                  })
+            if objtype in ('constant'):
+                name = content.strip().split()[0]
+                items.append({
+                                'start_line': start, 
+                                'end_line':   end, 
+                                'objtype':    objtype,
+                                'name':       name,
+                                'parent':     None,
+                              })
+            else:
+                for var in variable_name_re.finditer(content):
+                    name = var.group(1)
+                    if len(name) > 0:
+                        items.append({
+                                        'start_line': start, 
+                                        'end_line':   end, 
+                                        'objtype':    objtype,
+                                        'name':       name,
+                                        'parent':     None,
+                                      })
         return items
 
@@ -427 +461 @@
                 s.append( '' )
                 s.append(r['text'])
+                s.append( '' )
             elif r['objtype'] in ('def', 'rdef', 'cdef', ):
                 # TODO: apply rules to suppress reporting under certain circumstances
@@ -437 +472 @@
                                               r['end_line']) )
                 s.append( '.. spec:%s:: %s' % ( r['objtype'], r['name'],) )
+                s.append('')
+                s.append(' '*4 + '*' + r['objtype'] + ' macro declaration*')
                 desc = r.get('description', '')
                 if len(desc) > 0:
@@ -442 +479 @@
                     for line in desc.splitlines():
                         s.append(' '*4 + line)
+                s.append( '' )
             elif r['objtype'] in ('function def', 'function rdef',):
                 # TODO: apply rules to suppress reporting under certain circumstances
@@ -453 +491 @@
                                               r['end_line']) )
                 s.append( '.. spec:%s:: %s(%s)' % ( objtype, r['name'], r['args']) )
+                s.append('')
+                s.append(' '*4 + '*' + r['objtype'].split()[1] + '() macro function declaration*')
                 desc = r.get('description', '')
                 if len(desc) > 0:
@@ -458 +498 @@
                     for line in desc.splitlines():
                         s.append(' '*4 + line)
-            elif r['objtype'] in ('local', 'global', 'constant'):
+                s.append( '' )
+            
+            # Why document local variables in a global scope?
+            elif r['objtype'] in ('global', 'constant'):
                 # TODO: apply rules to suppress reporting under certain circumstances
                 declarations.append(r)
-                s.append( '.. spec:%s:: %s' % ( r['objtype'], r['name']) )
-                desc = r.get('description', '')
-                if len(desc) > 0:
+                if r.get('parent') is None:
+                    s.append( '.. spec:%s:: %s' % ( r['objtype'], r['name']) )
                     s.append('')
-                    for line in desc.splitlines():
-                        s.append(' '*4 + line)
+                    if r['objtype'] in ('constant'):
+                        s.append(' '*4 + '*constant declaration*')
+                    else:
+                        s.append(' '*4 + '*' + r['objtype'] + ' variable declaration*')
+                    desc = r.get('description', '')
+                    if len(desc) > 0:
+                        s.append('')
+                        for line in desc.splitlines():
+                            s.append(' '*4 + line)
+                    s.append( '' )
 
         s += _report_table('Variable Declarations (%s)' % self.filename, declarations, 
-                          ('objtype', 'name', 'start_line',))
+                          ('objtype', 'name', 'start_line', 'summary', ))
         s += _report_table('Macro Declarations (%s)' % self.filename, macros, 
-                          ('objtype', 'name', 'start_line', 'end_line'))
+                          ('objtype', 'name', 'start_line', 'end_line', 'summary', ))
         s += _report_table('Function Macro Declarations (%s)' % self.filename, functions, 
-                          ('objtype', 'name', 'start_line', 'end_line', 'args'))
-        #s += _report_table('Findings from .mac File', self.findings, ('start_line', 'objtype', 'line',))
+                          ('objtype', 'name', 'start_line', 'end_line', 'args', 'summary', ))
+        #s += _report_table('Findings from .mac File', self.findings, ('start_line', 'objtype', 'line', 'summary', ))
 
         return '\n'.join(s)
@@ -494 +544 @@
     for d in itemlist:
         if d['start_line'] != last_line:
-            rows.append( tuple([str(d[key]).strip() for key in col_keys]) )
+            rowdata = [str(d.get(key,'')).strip() for key in col_keys]
+            rows.append( tuple(rowdata) )
         last_line = d['start_line']
     return make_rest_table(title, col_keys, rows, '=')
@@ -508 +559 @@
     :param str titlechar: character to use when underlining title as reST section heading
     :returns [str]: each list item is reST
-    
-    Example::
-
-        title = 'This is a reST table'
-        labels = ('name', 'phone', 'email')
-        rows = [
-                ['Snoopy',           '12345', 'dog@house'],
-                ['Red Baron',        '65432', 'fokker@triplane'],
-                ['Charlie Brown',    '12345', 'main@house'],
-                ]
-        print '\n'.join(make_rest_table(title, labels, rows))
-    
-    This results in this reST::
-    
-        This is a reST table
-        ====================
-        
-        ============= ===== ===============
-        name          phone email          
-        ============= ===== ===============
-        Snoopy        12345 dog@house      
-        Red Baron     65432 fokker@triplane
-        Charlie Brown 12345 main@house     
-        ============= ===== ===============
     """
+    # this is commented out since it causes a warning when building:
+    #  specmacrofileparser.py:docstring of sphinxcontrib.specmacrofileparser.make_rest_table:14: WARNING: Block quote ends without a blank line; unexpected unindent.
+    # -----
+    #    """
+    #    build a reST table
+    #        
+    #    :param str title: placed in a section heading above the table
+    #    :param [str] labels: columns labels
+    #    :param [[str]] rows: 2-D grid of data, len(labels) == len(data[i]) for all i
+    #    :param str titlechar: character to use when underlining title as reST section heading
+    #    :returns [str]: each list item is reST
+    #
+    #    Example::
+    #        
+    #        title = 'This is a reST table'
+    #        labels = ('name', 'phone', 'email')
+    #        rows = [
+    #                ['Snoopy',           '12345', 'dog@house'],
+    #                ['Red Baron',        '65432', 'fokker@triplane'],
+    #                ['Charlie Brown',    '12345', 'main@house'],
+    #        ]
+    #        print '\n'.join(make_rest_table(title, labels, rows, titlechar='~'))
+    #
+    #    This results in this reST::
+    #    
+    #        This is a reST table
+    #        ~~~~~~~~~~~~~~~~~~~~
+    #        
+    #        ============= ===== ===============
+    #        name          phone email          
+    #        ============= ===== ===============
+    #        Snoopy        12345 dog@house      
+    #        Red Baron     65432 fokker@triplane
+    #        Charlie Brown 12345 main@house     
+    #        ============= ===== ===============
+    #    
+    #    """
     s = []
     if len(rows) == 0:

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

@@ -2 +2 @@
 
 .. autospecdir:: ../macros/
+
+.. end