Ticket #10637: sage-sws2rst.rej

File sage-sws2rst.rej, 6.6 KB (added by pang, 9 years ago)
Line 
1--- sage-sws2rst
2+++ sage-sws2rst
3@@ -1,6 +1,38 @@
4 #!/usr/bin/env python
5 # -*- coding: utf-8 -*-
6+r"""
7+sage-sws2rst
8+============
9 
10+Translate a Sage worksheet file (.sws) into an rst file.
11+
12+Usage::
13+
14+    sage --sws2rst [-h] <source sws file>
15+
16+Print the help message::
17+
18+    sage --sws2rst -h
19+
20+EXAMPLES::
21+
22+    sage --sws2rst file.sws
23+
24+The sws file should be in the current directory; using an
25+absolute path will result in an error.
26+
27+AUTHOR:
28+
29+    - Pablo Angulo (January 2011): Initial version
30+    - Karl-Dieter Crisman (June 2012): Documentation
31+      and minor refinements
32+"""
33+#############################################################################
34+#       Copyright (C) 2011 Pablo Angulo
35+#  Distributed under the terms of the GNU General Public License (GPL)
36+#  The full text of the GPL is available at:
37+#                  http://www.gnu.org/licenses/
38+#############################################################################
39 import sys
40 import tarfile
41 import os
42@@ -9,8 +41,12 @@
43 import tempfile
44 from sagenb.misc.worksheet2rst import worksheet2rst
45 
46+from optparse import OptionParser
47+
48+
49+# function where everything happens
50 def process_sws(file_name):
51-   
52+
53     sws_file = tarfile.open(file_name, mode='r:bz2')
54     #TODO: python complains about using tempnam, but I don't
55     #know hot to fix it or see any danger
56@@ -24,7 +60,7 @@
57     images_dir = base_name_clean + '_media'
58     if not os.path.exists(images_dir):
59         os.mkdir(images_dir)
60-   
61+
62     #"data" dir
63     data_path = os.path.join(tempname,'sage_worksheet','data')
64     if os.path.exists(data_path):
65@@ -33,15 +69,23 @@
66                 shutil.move(os.path.join(data_path, image), os.path.join(images_dir, image.replace(' ','_')))
67             except shutil.Error:
68                 pass
69-   
70+
71     #cells
72-    cells_path = os.path.join(tempname,'sage_worksheet','cells')   
73-    for cell in os.listdir(cells_path):
74-        cell_path = os.path.join(cells_path, cell)
75-        for image in os.listdir(cell_path):
76-            shutil.copy2(os.path.join(cell_path, image), 
77-                         os.path.join(images_dir, 'cell_%s_%s'%(cell,image)))
78-   
79+    cells_path = os.path.join(tempname,'sage_worksheet','cells')
80+    if os.path.exists(cells_path):
81+        for cell in os.listdir(cells_path):
82+            cell_path = os.path.join(cells_path, cell)
83+            for image in os.listdir(cell_path):
84+                if os.path.isfile(os.path.join(cell_path, image)):
85+                    shutil.copy2(os.path.join(cell_path, image),
86+                                 os.path.join(images_dir, 'cell_%s_%s'%(cell,image)))
87+                # could be Jmol image directory - code for future
88+                #elif os.path.isdir(os.path.join(cell_path, image)):
89+                #    if image == '.jmol_images':
90+                #        for jmolimg in os.listdir(os.path.join(cell_path, image)):
91+                #            shutil.copy2(os.path.join(cell_path, image, jmolimg),
92+                #                     os.path.join(images_dir, 'cell_%s_%s'%(cell,jmolimg)))
93+
94     #read html file, parse it, write rst file
95     file = codecs.open(os.path.join('.',tempname,'sage_worksheet','worksheet.html'),
96                           mode='r',
97@@ -54,15 +98,92 @@
98                   encoding='utf-8')
99     out_file.write(rst_text)
100     out_file.close()
101-   
102+    print "File at "+rst_file
103+    print "Image directory at "+images_dir
104+
105     shutil.rmtree(tempname)
106-   
107-if __name__=='__main__':
108-    if len(sys.argv)<=1:
109-        print 'First argument should be a sws file'
110-        sys.exit()
111-    for file_name in sys.argv[1:]:
112-        print file_name
113+
114+
115+# Set the parser
116+usage = r"""
117+
118+    sage -sws2rst [options]  <source sws file> ...
119+
120+Translate a Sage worksheet file (.sws) into an reStructuredText
121+(.rst) file.  At least one sws file argument is required; all sws
122+files will be parsed and translated.  Spaces in the names of the
123+worksheet will be converted to underscores.
124+
125+Examples:
126+
127+    sage --sws2rst file.sws
128+    sage --sws2rst file1.sws file2.sws file3.sws
129+    sage --sws2rst -h # this help message prints
130+    sage --sws2rst --sphinxify # information about how to use
131+                               # Sphinx to compile your rst file
132+
133+Remark:
134+
135+    The sws file(s) should be in the current directory; using an
136+    absolute path will result in an error."""
137+
138+sphinxify_text = r"""
139+
140+Once you have made your rst file, what can you do with it?
141+
142+If this is a file which is likely to become part of the Sage
143+standard documentation, you will want to edit the appropriate
144+file in $SAGE_ROOT/devel/sage/doc to include your file, or
145+simply include your file as appropriate.
146+
147+However, you may simply want to make great-looking documentation
148+for some other purpose out of your worksheet.  The following
149+steps are one way to do so.
150+
151+ - Assume that the generated .rst file is ``My_Project.rst``.
152+ - Make a folder somewhere convenient to compile in, say, ``MyProject``.
153+ - Then move your .sws file into that folder, and cd into it.
154+ - Now the key is to use Sage's shell to run Sphinx on it! Run ``sage --sh``.
155+ - Then type ``sphinx-quickstart`` and follow the instructions in the
156+   Sphinx tutorial [1]_. You will probably want to choose to render math
157+   with MathJax [2]_, but you can accept the defaults for the other options.
158+ - Finally, edit ``index.rst`` by adding ``My_Project`` in the table of
159+   contents, as detailed in the Sphinx tutorial [3]_.
160+ - If you now type ``make html`` you should get a beautiful-looking web page
161+   in ``_build/html``. If you did not have a header at the top of your worksheet,
162+   you may get an error, but you can ignore this.
163+
164+REFERENCES:
165+
166+.. [1] First Steps with Sphinx,
167+   http://sphinx.pocoo.org/tutorial.html
168+.. [2] MathJax,
169+   http://www.mathjax.org/
170+.. [3] Defining Document Structure, First Steps with Sphinx,
171+   http://sphinx.pocoo.org/tutorial.html#defining-document-structure"""
172+
173+parser = OptionParser(usage=usage)
174+parser.add_option("--sphinxify",
175+                  action="store_true", dest="sphinxify",
176+                  help="Print information about how to use Sphinx to compile your rst file, then exit.")
177+(options, args) = parser.parse_args()
178+
179+# Parse option
180+if options.sphinxify:
181+    print sphinxify_text
182+    sys.exit(0)
183+
184+# Parse arguments
185+if len(args) < 1:
186+    parser.print_usage()
187+    sys.exit(1)
188+
189+for file_name in args:
190+    print "Processing "+file_name
191+    try:
192         process_sws(file_name)
193-
194-
195+    except Exception as e:
196+        print "Unable to process file ('%s')" % file_name
197+        print "Error message: %s" % e
198+        print "Exiting."
199+        sys.exit(1)