Ticket #10637: trac_10637-root-docsandmore.patch

File trac_10637-root-docsandmore.patch, 7.0 KB (added by kcrisman, 9 years ago)

Apply to root repository

  • sage-sws2rst

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