Changeset 994

Timestamp:

Jul 6, 2012 2:15:32 PM (11 years ago)

Author:

jemian

Message:

refs #8, add autospecdir, no options supported yet

Location:

specdomain/trunk/src/specdomain

Files:

• sphinxcontrib/specdomain.py (modified) (3 diffs)
• sphinxcontrib/specmacrofileparser.py (modified) (4 diffs)
• test/ccdscan_4.0.mac.rst (modified) (1 diff)
• test/cdef-examples.mac.rst (modified) (1 diff)
• test/shutter.mac.rst (modified) (1 diff)
• test/test-battery.mac.rst (modified) (1 diff)
• test/test_autospecdir.rst (added)
• test/test_doc.rst (modified) (2 diffs)
• test/usaxs_load.mac.rst (modified) (1 diff)
• test/usaxs_uascan.mac.rst (modified) (1 diff)

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

@@ -130 +130 @@
         #self.add_directive_header(sig)
         
-        # TODO: provide links from each to highlighted source code blocks (like Python documenters).
-        # This works for now.
         self.add_line(u'', '<autodoc>')
         self.add_line(u'.. index:: SPEC macro file; %s' % macrofile, '<autodoc>')
         self.add_line(u'.. index:: !%s' % os.path.split(macrofile)[1], '<autodoc>')
         self.add_line(u'', '<autodoc>')
+        self.add_line(u'', '<autodoc>')
+        title = 'SPEC Macro File: %s' %  macrofile
+        self.add_line('@'*len(title), '<autodoc>')
+        self.add_line(title, '<autodoc>')
+        self.add_line('@'*len(title), '<autodoc>')
+        self.add_line(u'', '<autodoc>')
+        # TODO: provide links from each to highlighted source code blocks (like Python documenters).
+        # This works for now.
         line = 'source code:  :download:`%s <%s>`' % (macrofile, macrofile)
         self.add_line(line, macrofile)
@@ -165 +171 @@
                                 'given for autospecmacro %s' % self.fullname)
         return ret
+
+
+class SpecDirDocumenter(Documenter):
+    objtype = 'specdir'
+    member_order = 50
+    priority = 0
+    #: true if the generated content may contain titles
+    titles_allowed = True
+    option_spec = {
+        'include_subdirs': bool_option,
+    }
+
+    @classmethod
+    def can_document_member(cls, member, membername, isattr, parent):
+        return membername in ('SpecDirDocumenter', )
+    
+    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.
+        """
+        # now, parse the .mac files in the SPEC directory
+        specdir = self.name
+#        self.add_line(u'', '<autodoc>')
+#        self.add_line(u'directory:\n   ``%s``' % specdir, '<autodoc>')
+        if os.path.exists(specdir):
+            for f in sorted(os.listdir(specdir)):
+                filename = os.path.join(specdir, f)
+                if os.path.isfile(filename) and filename.endswith('.mac'):
+                    # TODO: support a user choice for pattern match to the file name (glob v. re)
+                    # TODO: support the option to include subdirectories (include_subdirs)
+                    # TODO: do not add the same SPEC macro file more than once
+                    self.add_line(u'', '<autodoc>')
+                    self.add_line(u'.. autospecmacro:: %s' % filename, '<autodoc>')
+                    # TODO: any options?
+                    self.add_line(u'', '<autodoc>')
+                    # TODO: suppress delimiter after last file
+                    self.add_line(u'-'*15, '<autodoc>')         # delimiter between files
+        else:
+            self.add_line(u'', '<autodoc>')
+            self.add_line(u'Could not find directory: ``%s``' % specdir, '<autodoc>')
+
 
 
@@ -355 +404 @@
     app.add_domain(SpecDomain)
     app.add_autodocumenter(SpecMacroDocumenter)
+    app.add_autodocumenter(SpecDirDocumenter)
     app.add_config_value('autospecmacrodir_process_subdirs', True, True)

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

@@ -381 +381 @@
         macros = []             # def, cdef, and rdef macros
         functions = []          # def and rdef function macros
-        #title = 'Extended Comments'
-        #s = ['', title, '='*len(title), ]
         s = []
         for r in self.findings:
             if r['objtype'] == 'extended comment':
+                # TODO: apply rules to suppress reporting under certain circumstances
                 s.append( '' )
                 s.append( '.. %s %s %d %d' % (self.filename, 
@@ -394 +393 @@
                 s.append(r['text'])
             elif r['objtype'] in ('def', 'rdef', 'cdef', ):
+                # TODO: apply rules to suppress reporting under certain circumstances
                 macros.append(r)
                 s.append( '' )
@@ -402 +402 @@
                                               r['end_line']) )
                 s.append( '' )
+                # TODO: make this next be part of the signature display (in specdomain)
                 s.append( '.. rubric:: %s macro declaration' % r['objtype']  )
                 s.append( '' )
-                #s.append( '.. spec:%s:: %s %s' % ( r['objtype'], r['name'], r['args'],) )
                 s.append( '.. spec:%s:: %s' % ( r['objtype'], r['name'],) )
             elif r['objtype'] in ('function def', 'function rdef',):
-                # FIXME:  not getting here, such as for kohzuE_cmd()
+                # TODO: apply rules to suppress reporting under certain circumstances
                 functions.append(r)
                 s.append( '' )
@@ -420 +420 @@
                 s.append( '.. spec:%s:: %s(%s)' % ( r['objtype'], r['name'], r['args']) )
             elif r['objtype'] in ('local', 'global', 'constant'):
+                # TODO: apply rules to suppress reporting under certain circumstances
                 del r['text']
                 declarations.append(r)
 
-        s += report_table('Variable Declarations', declarations, ('start_line', 'objtype', 'name', 'line',))
-        s += report_table('Macro Declarations', macros, ('start_line', 'name', 'line',))
-        s += report_table('Function Macro Declarations', functions)
+        s += report_table('Variable Declarations (%s)' % self.filename, declarations, ('start_line', 'objtype', 'name', 'line',))
+        s += report_table('Macro Declarations (%s)' % self.filename, macros, ('start_line', 'name', 'line',))
+        s += report_table('Function Macro Declarations (%s)' % self.filename, functions)
         #s += report_table('Findings from .mac File', self.findings, ('start_line', 'objtype', 'line',))
 

specdomain/trunk/src/specdomain/test/ccdscan_4.0.mac.rst

@@ -1 +1 @@
 .. $Id$
 
-=============================================================
-SPEC macro source file: ``../macros/ccdscan_4.0.mac``
-=============================================================
-
 .. autospecmacro:: ../macros/ccdscan_4.0.mac

specdomain/trunk/src/specdomain/test/cdef-examples.mac.rst

@@ -1 +1 @@
 .. $Id$
 
-=============================================================
-SPEC macro source file: ``../macros/cdef-examples.mac``
-=============================================================
-
 .. autospecmacro:: ../macros/cdef-examples.mac

specdomain/trunk/src/specdomain/test/shutter.mac.rst

@@ -1 +1 @@
 .. $Id$
-
-====================================================
-SPEC macro source file: ``../macros/shutter.mac``
-====================================================
 
 .. caution:: This file is as-received.  

specdomain/trunk/src/specdomain/test/test-battery.mac.rst

@@ -1 +1 @@
 .. $Id$
 
-========================================================
-SPEC macro source file: ``../macros/test-battery.mac``
-========================================================
-
 .. autospecmacro:: ../macros/test-battery.mac

specdomain/trunk/src/specdomain/test/test_doc.rst

@@ -96 +96 @@
 constant declaration:  
 
-        .. spec:local:: TWO_PI
+        .. spec:constant:: TWO_PI
         
            ``TWO_PI`` is the ratio of a circle's circumference to its diameter.
@@ -150 +150 @@
 
    *.mac
+   test_autospecdir

specdomain/trunk/src/specdomain/test/usaxs_load.mac.rst

@@ -1 +1 @@
 .. $Id$
 
-=============================================================
-SPEC macro source file: ``../macros/usaxs_load.mac``
-=============================================================
-
 .. autospecmacro:: ../macros/usaxs_load.mac

specdomain/trunk/src/specdomain/test/usaxs_uascan.mac.rst

@@ -1 +1 @@
 .. $Id$
 
-=============================================================
-SPEC macro source file: ``../macros/usaxs_uascan.mac``
-=============================================================
-
 .. autospecmacro:: ../macros/usaxs_uascan.mac