Professional Documents
Culture Documents
Background
As part of the grand reorganization of the various tools and software associated with the Runestone
Interactive project I am planning to also write a series of tutorials to help people get started. The major
aspects of this reorganization are discussed in detail in the Project Roadmap, but for the sake of some
context I can summarize the major efforts as follows:
1. Separate the distribution and development of writing tools from the server.
1. Make a pip installable runestone package.
2. Remove the interconnectedness between the components and Sphinx. In other words
support the user of runestone tools in environments like Markdown, and even wysiwyg html
editors.
2. Re-architect the server side focusing on services for the writing tools
1. Create an authentication service that supports CORS for cross domain AJAX use.
2. Create a standard REST API for logging and storing student data
3. Create a web application (or integrate with another) for grading
Since I just completed Part 1.1 I thought it was a good time to talk about how easy it is for you to now
use the runestone tools for creating a lab for your students, or lecture notes and presentation materials
for your class.
Getting Started
The major steps in getting started are
Installing Python
Installing the runestone tools
Building your first lab
Install Python
1. If you are on a Mac you are already done with this step.
2. If you are on Windows you will need to go to Python.org and download Python3.x. The windows
installer is a typical installer and you can just click your way through it.
If you are an advanced Python user you may want to may want to create a virtualenvironment for
this project but it is not a requirement.
If you are on Windows you may want to edit your PATH environment variable following the
instructions here. Again, mac users can ignore this.
From now on I'm only going to give the Mac way of running the commands. If you are on windows you
will need to add C:\\Python34\Scripts to the beginning of the command and add .exe to the end.
You can watch as a lot of text goes scrolling by. But as long as you don't get any errors you should be
good to go. You only need to do these first two steps once. Once you have installed Python and
runestone you will not have to do it again.
$ mkdir mynewproject
$ cd mynewproject
$ runestone init
At this point you will have the following files and folders:
mynewproject/
_static/
_sources
_templates
conf.py
pavement.py
=====================
This Is A New Project
=====================
SECTION 1: Introduction
:::::::::::::::::::::::
Congratulations! If you can see this file you have probably successfully run the ``runestone
This is just a sample of what you can do. The index.rst file is the table of contents for your
The overview section, which follows is an ideal section to look at both online and at the sourc
.. toctree::
:maxdepth: 2
overview.rst
If you are not familiar with markup languages, this file should still be quite readable to you, and you can
probably easily guess what most things do. Runestone uses a markup language called
restructuredText. There is a very nice, short tutorial here.
To give you an idea of what you see in the example above, the section that starts with .. toctree:: is
called a directive and it creates a table of contents for you. the maxdepth part sets the table of contents
to show sections and subsections. And the line with overview.rst indicates that it is a file that should
be included in the overall web page. More on all of this later. Our first task is simply going to be to wipe
everything out, and start over. Using a plain text editor change index.rst to look like this:
=============
My Sample Lab
=============
.. activecode:: turtle1
import turtle
timmy = turtle.Turtle()
for i in range(4):
timmy.forward(100)
timmy.right(90)
Now it is your turn. Can you modify the program to make timmy draw an octagon instead of
Now save the file and rerun the runestone build command. Everything should build without a
problem and you can now run runestone serve and open up http://localhost:8000 from your
browser. Notice that you can change the program and rerun it right from your browser.
It is probably obvious that you can create headings and subheadings. Unordered lists are created
using * and the runnable code examples are created by the .. activecode:: directive. The name
turtle1 must be unique on the webpage, other than that it is not used for too much at this point. The rest
of the activecode directive contains plain old python code, but it must be indented to line up with
the a in activecode. All indented lines are included as the body of the activecode directive, regular
text processing starts at the first unindented line.
There you have it. You have created a very nice little lesson without a lot of hassle. The Runestone and
Sphinx tools take care of all of the formatting for you!
Coming Soon
There are many free web hosting solutions out there and you can also choose one of them and upload
your project folder for hosting there. I'll cover at least one of them in another tutorial. In fact I think I see
a whole series of tutorials in the future on topics such as:
Making an online quiz for class
Making a lecture or presentation
Hosting your lab or quiz on github pages or another online service
Using your lab with runestone services