The OpenDSA Developer's Getting Started Guide

From OpenDSA Active-eBook Project
Jump to: navigation, search

The OpenDSA project uses several technologies to achieve its goals. Most people getting started will only be working on one part of the project, so you can focus on just the parts that are relevant to you.


Contents

Forums and Communications

The primary discussion forum for topics related to OpenDSA and JSAV is at: http://algoviz.org/forum/277. You need to be a registered user at AlgoViz.org (at the "trusted" level) to be able to post there. It is important for all developers to be registered at AlgoViz.org and to have notifications turned on to receive updates about forum discussions, because this is how you will be notified of new releases and other important changes to the project software.

Issues related to any of the repositories should be posted to their respective GitHub issue trackers.

Repositories

Main development is done out of repositories hosted at GitHub. Here are the ones that we use:

You can see a mirror for all of these repositories, and any files mentioned below, at http://algoviz.org/OpenDSA. For example, http://algoviz.org/OpenDSA/JSAV will mirror the JSAV stable release, http://algoviz/OpenDSA/build will mirror the built version of the modules, and so on.

Stable vs. Development Repositories and Official Mirrors

The repositories listed in the previous section are developer versions. We also maintain "stable" releases at SourceForge. The stable release is mirrored at: http://algoviz.org/OpenDSA/. Going to that URL will show you the OpenDSA project homepage, but any of the subdirectories (such as AV, Exercises, build, and JAV) will let you see the directory structure for the subdirectory.

Users who want the stable release (people who want to use the materials rather than develop them) would do best to get the stable release. If you want to get it under SVN control for easy updates, do:

svn co https://openalgoviz.svn.sourceforge.net/svnroot/openalgoviz/OpenDSA/trunk OpenDSA

Those who just want a simple zip file with the full OpenDSA distribution, go to http://sourceforge.net/projects/openalgoviz/files/OpenDSA/OpenDSA.zip/download .

Developers should be using stable releases where appropriate. For example, if you are a module, AV, or exercise developer, you should probably be linking to the stable version of JSAV rather than to the developer version (unless what you are doing is so bleeding edge that you temporarily need to access the developer version for the latest updates). The stable release of JSAV is available at http://algoviz.org/OpenDSA/JSAV/build/JSAV-min.js, and the CSS file is available at http://algoviz.org/OpenDSA/JSAV/css/JSAV.css. You should be using those links in your HTML files unless you have a really good reason for doing otherwise.

If you want to see a mirror of the development versions for OpenDSA and JSAV, they are at http://algoviz.org/OpenDSA/dev/OpenDSA and http://algoviz.org/OpenDSA/dev/OpenDSA/JSAV, respectively.

Module Development

Modules for OpenDSA are written in reStructuredText (and thus module files use the suffix .rst), and are compiled into HTML files using the Sphinx compiler. You can easily convert all of the existing modules to HTML files by running "make" from the RST directory. Thus, the full workflow will typically require that you install the following on your machine:

Documentation for using Sphinx and reStructuredText can be found at http://sphinx.pocoo.org/contents.html.

Exercise Development

If you would like to design and implement Khan Academy-style exercises, then you will be using the khan-exercises repository mentioned above. The parts of the KA infrastructure that we use are included in the OpenDSA distribution. However, if you want your own copy of the original, you can get it with:

git clone git://github.com/Khan/khan-exercises.git khan-exercises

You should take a look at OpenDSA/Exercises for examples of exercises that we have written, including ones that use JSAV. You can also look at https://github.com/Khan/khan-exercises/wiki/Good-examples-and-pro-tips to see some examples, ideas, and tips from the developers at Khan Academy. You will need to read the documentation provided by Khan Academy (https://github.com/Khan/khan-exercises/wiki/Writing-Exercises:-Home).

Note that you can view an exercise HTML page properly only if it has been processed by a web server. If you just have a local file on your PC that you look at with your web browser (with no web server running), then you won't see much. But there is a simple fix for this if you have Python installed. Look at ~OpenDSA/WebServer for how to run a simple local server in Python that you can use to do your testing.

We are beginning to investigate using Quadbase as a front end for exercise development (perhaps converting to KA-style format after creation). Quadbase is available at: https://github.com/lml/quadbase. This is implemented using Ruby-on-rails. We are also working on our own graphical front end for editing questions and converting them to KA format. Take a look at http://algoviz-beta.cc.vt.edu/QBank.

AV Development

We build our AVs with support from the JSAV development library. You can look at the various examples in the JSAV and OpenDSA repositories to help you get started. The documentation for JSAV is at JSAV/doc, which is mirrored at http://algoviz.org/OpenDSA/JSAV/doc. The JSAV API is documented at http://algoviz.org/OpenDSA/JSAV/doc/api.html, and there is a simple example of how to create a proficiency exercise at http://algoviz.org/OpenDSA/JSAV/doc/exercise.html. The official stable release version of JSAV can be linked to at http://algoviz.org/OpenDSA/JSAV/build/JSAV-min.js. If you need to use the development version of JSAV (most AV developers do not!), this is available at https://github.com/vkaravir/JSAV, mirrored at http://algoviz.org/OpenDSA/dev/OpenDSA/JSAV/build/JSAV-min.js

Note: If you want to be able to compile JSAV (which you will need to do if you are installing the developer's version instead of pulling the library from the Internet), then you must have Java installed to run the JavaScript minimizer tool.

JavaScript (and other programming) Resources

Since we do so much programming in JavaScript, newcomers will need good resources. One well-respected site is https://developer.mozilla.org/en/JavaScript. Beware of doing a search engine query and ending up at w3schools, which is not so well respected these days.

If you are at Virgina Tech (or if your school supports this), a wonderful source of documentation is the Safari database (http://proquest.safaribooksonline.com/?uicode=viva), which contains a huge collection of technical books including the entire O'Reilly catalog.

In-Book "live" Code Examples

We want our code examples given in the book to be in a real language so that we can test and debug them. Further than that, we want to be able to let readers edit and execute them. There are a couple of options for doing this. One is to use the language "Processing". This is a Java-derivative language. There is a processing.js library to support running Processing programs in the web browser. For more information, see: http://processingjs.org/learning/ . Another approach is to use Python. See http://thinkcspy.appspot.com/build/index.html for how Python can be edited and the result run in the browser. We can probably do exactly the same thing with Processing. For implementation details, see:

github.com/bnmnetp/eBookExtensions

github.com/bnmnetp/thinkcspy

Some Notes on Using git and GitHub

If you want to check out one of our GitHub repositories, you can do so as follows once you have "git" installed on your system.

For OpenDSA, type the following at the command line:

git clone git://github.com/cashaffer/OpenDSA.git OpenDSA

JSAV is a git submodule of OpenDSA. After pulling the OpenDSA repository, go to the toplevel directory of OpenDSA and do the following two commands:

git submodule init

git submodule update

This will install the JSAV repository. If you want just the JSAV repository without OpenDSA, type the following at the command line:

git clone git://github.com/vkaravir/JSAV.git JSAV

The lines above will give you "read only" copies of the repositories. You can update to the latest version at anytime by going to your directory that holds the repository and typing:

git pull

git submodule update

You should always do that prior to doing any work on the source files. Be sure to do both commands every time, to make sure that you catch any changes to the JSAV submodule.

If you need permission to contribute to the OpenDSA repository, contact Cliff Shaffer <shaffer at vt.edu>. You will need to have an account at GitHub. There are two ways to get set up to be able to commit changes to the repository. The cleanest is to do the checkout so that your copy is read/write by using the following checkout command instead of the one indicated above:

git clone https://YOURGITHUBID@github.com/cashaffer/OpenDSA.git OpenDSA

To do this, you must already have permission to commit back to the repository. What might be a more typical scenario is that you have already cloned the repository as read-only. In that case, you just need to edit the .git/config file to change the URL line to be: https://YOURGITHUBID@github.com/cashaffer/OpenDSA.git

Pushing changes to the repository in "git" is a two-stage process. First, for each file that you modify you must do:

git add <filename>

Then, when you want to do a commit, do:

git commit

This will take you to an editor to add comments. Never commit anything to the repository without including a clear and concise comment about what you have changed! Also, avoid "git commit -a" since that is sure to bring you to grief sometime with the relationships between the repository and its submodules. Best practice is to explicitly add each file that you have modified and that you intend to save. If you feel that this is a burden because you think that you are having to add too many files by hand, then you are probably not committing frequently enough. You can do multiple commits if you like before a push. But the important thing to understand is that "git commit" does not save anything, it merely "stages" things locally. To actually move anything into GitHub so that others can see the changes, you must finish the process by using:

git push

Charts and Graphs

Look at Google Charts API: http://code.google.com/apis/chart/image/. This is a simple way to make charts by handing it a URL. We could construct a URL from data in JavaScript, and then we have a chart to display in a module.

For laying out graphs (in the mathematical sense, not the data graphics sense), try Graphviz: http://www.graphviz.org/. There is an experimental Google Chart Tools frontend described at http://code.google.com/apis/chart/image/docs/gallery/graphviz.html.

"Front End" Development

The "front end" refers to infrastructure that supports organizing and viewing collections of modules. Eric is working on this, and we need to get his work committed to a repository. Notes will be forthcoming.

"Back End" Development

We are experimenting with the Khan Academy infrastructure for supporting anything that has to track the progress of users, and for generating a Knowledge Map. Information about installing the KA back end is available at: https://sites.google.com/a/khanacademy.org/forge/for-developers/new-developers/dev-environment-setup . To do a full KA site installation, you will need the following:

We have a version of this, modified to "skin" for OpenDSA, installed at /home/algoviz-beta/OpenDSA/stableExp.

Installing Tools on Windows

You can get GNU make for Windows at http://gnuwin32.sourceforge.net/packages/make.htm .

On Windows, I have only tested GNU make, using the bash shell that comes with the Git distribution for my environment.

You will need to be sure that Git, Python, Java, and make are on your path. On Windows 7, you edit your path variable by right-clicking your Computer icon, clicking on "Advanced system settings" and then "Environment Variables". If you have a 64-bit operating system, be aware that the various GNU tools will not work properly if they see "Program Files (x86)" on the system path variable. You might need to install these tools elsewhere, and/or reorder things on the path so that the GNU tool appears before anything referencing "Program Files (x86)".

Beware if you have Cygwin installed on your Windows machine: There might be path conflicts between Cygwin on the one hand, and the Git Shell and the GNU tools on the other. If you insist on trying to use both on your system, you are on your own. Otherwise you have two reasonable options:

Retrieved from "http://www.algoviz.org/algoviz-wiki/index.php/The_OpenDSA_Developer%27s_Getting_Started_Guide"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox