How Runestone works?

How Runestone Works?

• Helpful notes from Siwei "Robert" Li

Wish the following content will be helpful for new developers who want to contribute to Runestone. I'll suggest useful resources below for learning about the stack upon which the project is based.

---

Major Technologies Used for Runestone Components:

• Python

  • Python 2
  • Sphinx
    • reStructuredText (.rst)
    • Writing Sphinx Extensions
  • Basic Python Packaging
    • The Github repo has some info on setting up. You don't necessarily need virtualenv, using Conda is fine.

• Web Technologies

  • Front-end
    • JavaScript
    • CodeMirror library (heavily relied on by ActiveCode)
    • Bootstrap Framework (v2-3)
    • JQuery
  • Back-end(for Runestone Server)
    • Web2Py (In most cases you won't touch it)

There are plenty of free online tutorials on web technologies mentioned above.

---

How they work together:

Runestone Component is like a wrapper of Sphinx, which helps you generate a sphinx project with a collection of Sphinx extensions that adds unique directives and functionalities to reStructuredText markup language, including ActiveCode (running code in the browser), making timed exams or casual quizs with multiple choice, Parson questions, or actuall coding questions and so on.

Sphinx reads reStructuredText and convert it to static html pages. On the official website of Sphinx there's a nice tutorial for writing Sphinx extensions, which is about the python part of the project.

And most of the front-end functionality is implemented through JavaScript and its third-party libraries. Sphinx python extensions are responsible for adding JavaScript files to the head of generated html files. And JavaScript files scan through the html DOM to render the respective directives defined by Runestone.