Ticket #12299: trac_12299-reviewer.patch

doc/en/reference/interfaces.rst

@@ -78 +78 @@
    sage/interfaces/sage0
    sage/interfaces/singular
    sage/interfaces/tachyon
+   sage/interfaces/jmoldata

sage/interfaces/jmoldata.py

@@ -5 +5 @@
 reads and for generating image files. 
 
 AUTHORS:
-Jonathan Gutow (2012-06-14): complete doctest coverage
-Jonathan Gutow (2012-03-21): initial version
+
+- Jonathan Gutow (2012-06-14): complete doctest coverage
+- Jonathan Gutow (2012-03-21): initial version
+"""
 
 #*******************************************************************************
 #       Copyright (C) 2012 Jonathan Gutow (gutow@uwosh.edu)
@@ -16 +18 @@
 #  the License, or (at your option) any later version.
 #                  http://www.gnu.org/licenses/
 #*******************************************************************************
-"""
+
 from sage.structure.sage_object import SageObject
 
 from sage.misc.misc import tmp_filename
@@ -28 +30 @@
 class JmolDataError(Exception):
 
     def __init__(self, value):
-    """
-    EXAMPLES:
+        """
+        TEST::
 
-    JmolDataError __init__ test::
-        sage: from sage.interfaces.jmoldata import JmolDataError
-        sage: print(JmolDataError("test of init").value)
-        test of init
-    """
+            sage: from sage.interfaces.jmoldata import JmolDataError
+            sage: print(JmolDataError("test of init").value)
+            test of init
+        """
         self.value = value
+
     def __str__(self):
-    """
-    EXAMPLES:
+        """
+        TEST::
 
-    JmolDataError __str__ test::
-
-        sage: from sage.interfaces.jmoldata import JmolDataError
-        sage: print str(JmolDataError("test of error"))
-        'test of error'
-    """
+            sage: from sage.interfaces.jmoldata import JmolDataError
+            sage: print str(JmolDataError("test of error"))
+            'test of error'
+        """
         return repr(self.value)
 
 class JmolData(SageObject):
     r"""
-    .. TODO::
-        DONE 1) create an image file (user choosable JPG, PNG, GIF)
-        DONE 1.5) function to check if jvm is available
-        DONE 1.75) raise exception if export_image is called without JVM being available.
-        2) create an animated image file if spin is on (GIF)
-        3) Put data extracted from a file into a variable/string/structure to return 
+    .. todo::
+
+       Create an animated image file (GIF) if spin is on and put data
+       extracted from a file into a variable/string/structure to return
     """
     def __init__(self):
         """
         EXAMPLES:
 
-        Create a JmolData object
-        ::
+        Create a JmolData object::
 
             sage: from sage.interfaces.jmoldata import JmolData
             sage: JData = JmolData()
@@ -108 +105 @@
         This executes JmolData.jar to make an image file.
 
         INPUT:
-            targetfile -- the full path to the file where the image should be written.
-            datafile   -- full path to the data file Jmol can read or text of a script 
-                telling Jmol what to read or load.
-            datafile_cmd -- "script" or "load" defaults to "script", should be load for a data file.
-            image_type -- "PNG" "JPG" or "GIF" defaults to "PNG"
-            figsize -- number = (pixels/side)/100 defaults to 5.
+
+        - targetfile -- the full path to the file where the image
+          should be written.
+
+        - datafile -- full path to the data file Jmol can read or
+          text of a script telling Jmol what to read or load.
+
+        - datafile_cmd -- (default ``'script'``)  ``'load'`` or ``'script'``
+          should be ``"load"`` for a data file.
+
+        - image_type -- (default ``"PNG"``) ``'PNG'`` ``'JPG'`` or ``'GIF'``
+
+        - figsize -- number (default 5) equal to (pixels/side)/100
 
         OUTPUT:
-            image file , .png, .gif or .jpg (default .png)
 
-        .. NOTE::
-            Examples will generate an error message if a functional Java Virtual Machine (JVM) is not installed
-            on the machine the Sage instance is running on.
+        Image file , .png, .gif or .jpg (default .png)
 
-        .. WARNING::
-            Programmers using this module should check that the JVM is available before making calls to
-            avoid the user getting error messages.  Check for the JVM using the function 
-            is_jvm_available(), which returns True if a JVM is available.
+        .. note::
+
+            Examples will generate an error message if a functional Java Virtual Machine (JVM)
+            is not installed on the machine the Sage instance is running on.
+
+        .. warning::
+
+            Programmers using this module should check that the JVM is
+            available before making calls to avoid the user getting
+            error messages.  Check for the JVM using the function
+            :meth:`is_jvm_available`, which returns True if a JVM is available.
 
         EXAMPLES:
 
-        Use Jmol to load a pdb file containing some DNA from a web data base and make an image of the DNA.
-        If you execute this in the notebook, the image will appear in the output cell.
-        ::
+        Use Jmol to load a pdb file containing some DNA from a web data
+        base and make an image of the DNA. If you execute this in the
+        notebook, the image will appear in the output cell::
 
             sage: from sage.interfaces.jmoldata import JmolData
             sage: JData = JmolData()
             sage: script = "load =1lcd;display DNA;moveto 0.0 { -473 -713 -518 59.94} 100.0 0.0 0.0 {21.17 26.72 27.295} 27.544636 {0.0 0.0 0.0} -25.287832 64.8414 0.0;"
-            sage: testfile = "DNA.png"
-            sage: JData.export_image(targetfile=testfile,datafile=script,image_type="PNG")
-            sage: print os.path.exists(testfile)
+            sage: testfile = tmp_filename()+"DNA.png"
+            sage: JData.export_image(targetfile=testfile,datafile=script,image_type="PNG") # optional -- internet
+            sage: print os.path.exists(testfile) # optional -- internet
             True
 
-        Use Jmol to save an image of a 3-D object created in Sage.  This method is used internally
-        by plot3d to generate static images.  This example doesn't have correct scaling.
-        ::
+        Use Jmol to save an image of a 3-D object created in Sage.
+        This method is used internally by plot3d to generate static images.
+        This example doesn't have correct scaling::
 
             sage: from sage.interfaces.jmoldata import JmolData
             sage: JData = JmolData()
@@ -152 +160 @@
             sage: archive_name=os.path.join(SAGE_TMP, "archive.jmol.zip")
             sage: D.export_jmol(archive_name)  #not scaled properly...need some more steps.
             sage: testfile = os.path.join(SAGE_TMP, "testimage.png")
-            sage: script = 'set defaultdirectory "'+archive_name+'"\n script SCRIPT\n'
+            sage: script = 'set defaultdirectory "%s"\\n script SCRIPT\\n'%archive_name
             sage: JData.export_image(targetfile =testfile,datafile = script, image_type="PNG")
             sage: print os.path.exists(testfile)
             True