Changeset 942

Timestamp:

Jun 18, 2012 6:19:12 PM (13 years ago)

Author:

jemian

Message:

refs #8, apply ANL's short-form license, starting to understand how to get content added, try additional test case SPEC macro file

Location:

specdomain/src/specdomain

Files:

• LICENSE (modified) (1 diff)
• sphinxcontrib/specdomain.py (modified) (4 diffs)
• test/test-battery.mac (added)
• test/test_doc.rst (modified) (2 diffs)

specdomain/src/specdomain/LICENSE ¶

@@ -1 @@
-If not otherwise noted, the extensions in this package are licensed
-under the following license.
+Copyright (c) 2011-2012, UChicago Argonne, LLC
 
-Copyright (c) 2010 by the contributors (see AUTHORS file).
-All rights reserved.
+All Rights Reserved
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
+specdomain
 
-* Redistributions of source code must retain the above copyright
-  notice, this list of conditions and the following disclaimer.
+BCDA, Advanced Photon Source, Argonne National Laboratory
 
-* Redistributions in binary form must reproduce the above copyright
-  notice, this list of conditions and the following disclaimer in the
-  documentation and/or other materials provided with the distribution.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+OPEN SOURCE LICENSE
+
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, 
+   this list of conditions and the following disclaimer.  Software changes, 
+   modifications, or derivative works, should be noted with comments and 
+   the author and organization's name.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation 
+   and/or other materials provided with the distribution.
+
+3. Neither the names of UChicago Argonne, LLC or the Department of Energy 
+   nor the names of its contributors may be used to endorse or promote 
+   products derived from this software without specific prior written 
+   permission.
+
+4. The software and the end-user documentation included with the 
+   redistribution, if any, must include the following acknowledgment:
+
+   "This product includes software produced by UChicago Argonne, LLC 
+   under Contract No. DE-AC02-06CH11357 with the Department of Energy."
+
+****************************************************************************
+
+DISCLAIMER
+
+THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY OF ANY KIND.
+
+Neither the United States GOVERNMENT, nor the United States Department 
+of Energy, NOR uchicago argonne, LLC, nor any of their employees, makes 
+any warranty, express or implied, or assumes any legal liability or 
+responsibility for the accuracy, completeness, or usefulness of any 
+information, data, apparatus, product, or process disclosed, or 
+represents that its use would not infringe privately owned rights.
+
+****************************************************************************

specdomain/src/specdomain/sphinxcontrib/specdomain.py ¶

@@ -4 +4 @@
     ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    SPEC domain.
-
-    :copyright: Copyright 2012 by Pete Jemian
-    :license: BSD, see LICENSE for details.
+    :synopsis: SPEC domain for Sphinx
+    
+    Automatically insert ReST-formatted extended comments 
+    from SPEC files for macro definitions and variable declarations into
+    the Sphinx doctree, thus avoiding duplication between docstrings and documentation
+    for those who like elaborate docstrings.
+
+    :copyright: Copyright 2012 by BCDA, Advanced Photon Source, Argonne National Laboratory
+    :license: ANL Open Source License, see LICENSE for details.
 """
 
@@ -25 +30 @@
 from sphinx.domains import Domain, ObjType, Index       #@UnusedImport
 from sphinx.util.compat import Directive                #@UnusedImport
-from sphinx.util.nodes import make_refnode
+from sphinx.util.nodes import make_refnode, nested_parse_with_titles
 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
+
 
 match_all                   = r'.*'
@@ -199 +208 @@
         '''
         extended_comments_list = self.parse_macro_file(sig)
+        view = ViewList([u'TODO: recognize the ReST formatting in the following extended comment and it needs to be cleaned up'])
+        node = nodes.paragraph()
+        node.document = self.state.document
+        self.state.nested_parse(view, 0, signode)
+        # TODO: recognize the ReST formatting in the following extended comment and it needs to be cleaned up
         for extended_comment in extended_comments_list:
-            linenumber = -1                 # FIXME:
-            #for line in prepare_docstring(extended_comment, ignore=1):
-            #    self.result.append(self.indent + line, sig, linenumber)     # FIXME:
+            for line in string2lines(extended_comment):
+                view = ViewList([line])
+                nested_parse_with_titles(self.state, view, signode)
         return sig
     
@@ -227 +241 @@
             #e = node.end()
             #t = buf[s:e]
-            results.append(node.groups())            # TODO: can we get line number also?
+            results.append(node.groups()[0])            # TODO: can we get line number also?
         return results
 

specdomain/src/specdomain/test/test_doc.rst ¶

@@ -147 +147 @@
 ..  This should document the Python module supporting the specdomain
 
+.. py:function:: test.testdoc.radius(x, y)
+        
+        :param float x: ordinate
+        :param float y: abcissa
+        :returns float: hypotenuse
+        
+        return math.sqrt(x*x + y*y)
+
 :class:`SpecVariableObject` (Python Module)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -160 +168 @@
 
 
-SPEC macro source file
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+SPEC macro source file: ``cdef-examples.mac``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. spec:macrofile:: cdef-examples.mac
+
+
+SPEC macro source file: ``test-battery.mac``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. spec:macrofile:: test-battery.mac