Creating a Tutorial from an old Sage Worksheet (.sws)¶
A lot of pedagogical material has been written in the Sage Worksheet format, which is no longer supported by Sage after the transition to Python 3 and the removal of the SageNB package.
However, it is possible to convert Sage Worksheet files. Once you have created a worksheet and are satisfied with the text and computations, download it to a directory.
We will assume here that the worksheet is called Tutorial.sws
and the directory is called make_tutorial. We also assume that
sage is your Sage command; if it is not in your PATH then replace
this with the path to your Sage installation, such as
/Applications/Sage-9.2.app/Contents/Resources/sage/sage if you are
using the Mac app and have placed it in your Applications directory.
Next, you will need an optional package to convert your worksheet. Use the command:
$ sage -i sage_sws2rst
to install it (or, in the Mac app, use the
Terminal Sessionadvanced menu).Then we will use the
sws2rstscript to turn the worksheet into a document in the ReStructuredText format. Be sure you are in the same directory as the worksheet:$ sage --sws2rst Tutorial.sws
This will create an
.rstfile along with a subdirectory of image files (which may be empty if there are no images).You can find help for
sws2rstwith the commandsage --sws2rst -honce you have installed beautifulsoup4.In principle, such a file could be added directly to Sage’s documentation (see the developer’s manual). However, you probably want to check whether it looks right first. So next we will compile this file to html documentation.
Follow the instructions of
sage --sws2rst --sphinxify. First, we will open a Sage shell session, where all appropriate Sage references already work properly:$ sage --sh
From here, you should be able to just type:
$ sphinx-quickstartand then respond to prompts for turning your
.rstfile into documentation. For most of them you can just hit enter/return to accept the defaults. However, you will probably want toEnter a name for the project
Enter a name for you
Type
yfor the question about using MathJax
Keep note of the instructions; the main other thing to do is add your file’s name to
index.rst, and then just do:$ make html
and wait while magic happens. To see the results, open the file
make_tutorial/_build/html/Tutorial.htmlwith a browser, or use your graphical file system to navigate to the same place.
Now you can modify the
.rstfile more and repeat the steps of compiling it until it is ready for inclusion, or just for distribution among other Sage users as an HTML file. (Domake pdffor a PDF version.)