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. If you are new, and you try to read this whole document, you will probably feel overwhelmed. However, most people when getting started will only work on one aspect of the project. So you should focus on just the sections here 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 and Official Mirrors

Main development is done out of repositories hosted at GitHub. We use a GitHub "organization" at https://github.com/OpenDSA. Here is a list of the individual repositories that we use:

The stable releases of OpenDSA and JSAV are mirrored at: http://algoviz.org/OpenDSA/ and http://algoviz.org/OpenDSA/JSAV, respectively. The built version of the stable modules are mirrored at: http://algoviz.org/OpenDSA/Books.

The development versions of OpenDSA and JSAV are mirrored at: http://algoviz.org/OpenDSA/dev/OpenDSA and http://algoviz.org/OpenDSA/dev/OpenDSA/JSAV, respectively.

File Structure and File Naming Conventions

The following refers to the OpenDSA content or "client side" repositories ("OpenDSA" and "OpenDSA-stable").

Content materials come in the form of modules (in RST), exercises, AVs, etc. There are various top-level directories, as explained below and in more detail in the project README file (https://github.com/OpenDSA/OpenDSA/blob/master/README.txt). Within the RST, AV, SourceCode and Exercises directories, the materials are subdivided into subdirectories based on topical content (such as Sorting). These content subdirectories are mirrored across all of the materials subtypes. That is, if there is a Sorting subdirectory in the AVs directory, there should also be one in the RST directory, Exercises directory and the SourceCode directory to match. In addition, each of the major top-level directories contains a subdirectory named Development. All content starts life in the Development subdirectory. Once it is completed, polished, validated, and had a thorough code review, Dr. Shaffer will move code out of the Development subdirectory to an appropriate content subdirectory.

Algorithm visualizations, proficiency exercises, and related code live in the AV directory.

Exercises built using the Khan Academy exercise infrastructure lives in the Exercises directory.

Tutorial modules live in the RST directory, with the actual source in RST/source.

Code examples that will be presented within the modules (such as Processing or Python code) lives in the SourceCode directory.

Individual files are further labeled by functional type. Files related to AVs have their filename end in AV (such as insertionsortAV.js). Files related to proficiency exercises end in PE. Files related to mini-slideshows or similar content that is included within a module end in CON. Khan Academy exercises that are multiple choice questions end in MC, and T/F questions end in TF. KA-based questions that are interactive (for example, where a user clicks on JSAV array elements to give an answer) end in INT. The practice is to put individual KA questions in separate files, and often these are then aggregated to present to students as a battery of "summary" questions. Such aggregations end in SUM.

OpenDSA Coding Standards

See CodingStandards for details on our project coding standards, and tools to support them.

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. A collection of RST files and associated exercises are made into "eBooks" using a configuration file (stored in the config directory). The top-level Makefile contains rules for a few sample books.

Tools

Module development requires the following tools to be installed on your machine:

AV Development

We build our AVs with support from the JSAV development library. Example AVs can be found in OpenDSA/AV/ and OpenDSA/JSAV/examples/, and documentation for JSAV can be found at OpenDSA/JSAV/doc/. 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.

The following tools are required to do AV development (see here for tool installation instructions):

Getting Started

To get a working copy of OpenDSA from our GitHub repository, you must have git, make, and java installed. See here for details about installing them. Now open a Git Bash command shell, and "cd" to where you want to put your copy of OpenDSA. Then type the following command at the command line: 

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

This will create a copy of the repository in "OpenDSA". Now "cd" to the "OpenDSA" directory and do the following two commands: 

git submodule init
make pull

All the necessary libraries should now be built and all example AVs should work.

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.

Proficiency Exercise Development

There is a simple example of how to create a proficiency exercise at http://algoviz.org/OpenDSA/JSAV/doc/exercise.html.

Web Programming Resources

Since we do so much webpage development and 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 Virginia 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.

Debugging and Code Validation Tools

When you right-click a web page in Chrome, you get a popup menu whose bottom item is "Inspect Element". This brings up the Chrome Developer Tools panel. This is especially helpful for inspecting the various DOM elements on your web page. A big help here is seeing the CSS styles in effect for any specified DOM element. For details on how to view and even edit on-the-fly your CSS settings in force (for example, to see what you should change), see https://developers.google.com/chrome-developer-tools/docs/elements-styles.

Firebug

While Chrome has built-in developer tools (and a lite version of Firebug), we highly recommend using the full version of Firebug, available for Firefox, for JavaScript debugging. The following list highlights some of Firebug's features and how they can be used.

More information about Firebug's features can be found here: https://getfirebug.com/

While we recommend using Firebug, and therefore Firefox, for development, testing should also be done using Chrome since the two browsers render content slightly differently.

jshint

Our coding standards are embodied in part by use of the jshint tool, run using the fairly strict settings defined in OpenDSA/.jshintrc . Before your code will be completely accepted by the project, it will have to pass this without any warnings. To get jshint on Windows:

  1. Install node.js (see http://nodejs.org and don't forget to check for the 64-bit version if that is the OS you are running).
  2. Then install jshint from the command line by doing: 
npm install jshint -g

Then so long as you are running it from anywhere inside the OpenDSA directory, if you run jshint it will invoke the options in the .jshintrc file for you.

csslint

Once you have jshint installed, then go ahead and install csslint as well by doing: 

npm install -g csslint

This will run a lint checker on your .css files.

To be able to lint check either JavaScript or CSS, you need to put it in separate files from your HTML code.

HTML Validation

You should also validate your HTML pages using the W3 validator. The easiest way to do this is to add a plugin to your browser. A good one is at http://chrispederick.com/work/web-developer/.

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

We are developing support for "live" code.

Using git and GitHub

Clone Code

To get a working copy of OpenDSA from our GitHub repository, you must have git and make installed. Next, type the following at the command line: 

git clone https://YOURGITHUBID@github.com/OpenDSA/OpenDSA.git OpenDSA
(read/write copy)

or 

git clone git://github.com/OpenDSA/OpenDSA.git OpenDSA
(read-only copy)

JSAV is distributed as a submodule of OpenDSA, so after pulling the OpenDSA repository, go to the top level directory of OpenDSA and run the following two commands: 

git submodule init
git submodule update

This will download the JSAV submodule, but it must be built before OpenDSA will function properly. To build JSAV, navigate to the JSAV directory and type "make".

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
(read-only copy)

You can update to the latest version at anytime by navigating to your OpenDSA root directory 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. Please note that if JSAV updates, you must rebuild it.

A much simpler approach is to just type "make pull" from the OpenDSA top-level directory. This will update all submodules, recompile JSAV if necesary, minimize all library files if necessary, and recompile the documentation if necessary.

In order to create a read / write copy of OpenDSA, you must have a GitHub account and permission to contribute to the OpenDSA repository. If you need permission, please contact Cliff Shaffer <shaffer at vt.edu> and include your GitHub username. There are two ways to get set up to be able to commit changes to the repository. The cleanest is to checkout a read/write copy using the command shown above. The second way assumes you have created a read-only clone of the repository. In that case, you just need to edit the .git/config file to change the URL line to be: https://YOURGITHUBID@github.com/OpenDSA/OpenDSA.git

Commit and Push Changes

Since git is a distributed repository system, pushing changes back to the "central" copy at GitHub is a two-stage process. First, for each file that you modify you must do: 

git add <filename>

Then, when you want to save your changes, do: 

git commit

This will take you to an editor to add comments.

We have two important rules related to commits:

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. You must push your changes to GitHub so that others can see them. Before you push changes you should ALWAYS run git pull. This will merge any changes from the repository with your local copy. If there are any conflicts, resolve them, commit your changes, pull again and, if successful, push to the repository. If you do not pull first, you may create conflicts in the central repository, breaking the code for everyone. This is a pain to fix, so always pull before you push.

After you have pulled (and resolved and committed any changes), you push your changes to GitHub using the following: 

git push

Example

Create a GitHub account and get permission to contribute to OpenDSA. 

git clone https://YOURGITHUBID@github.com/OpenDSA/OpenDSA.git OpenDSA
cd OpenDSA
git submodule init
make pull

Make your changes. For this example we assume that you modified 'lib/ODSA.js' 

git add lib/ODSA.js
git commit -m "<comment about what you changed>"
make pull
git push

In this series of commands, "make pull" was done just to make sure that nobody else committed since your last pull. It is OK of you leave this step out, git will just complain to you if you are not up-to-date (and force you to do the pull before you can push).

Tips and Tricks

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. Another library for charts is g.raphael at http://g.raphaeljs.com/.

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.

Client-side Framework

The client-side framework refers to that part of the OpenDSA infrastructure that runs in a client's browser. The framework support code that gets included by OpenDSA HTML is written in JavaScript and spread across 3 files:

Additional documentation can be found in OpenDSA/Doc. Sphinx and make are required to build the documentation.

Server-side Development

We are developing support for logging data about use of the modules, AVs, and exercises, and for tracking student performance. We have a GitHub project at: https://github.com/OpenDSA/OpenDSA-server. Tools necessary to work on the back end include:

There is a useful Django tutorial at https://docs.djangoproject.com/en/1.4/intro/tutorial01/.

We had been exploring the possibility of using the Khan Academy infrastructure for supporting anything that has to track the progress of users, and for generating a Knowledge Map. Unfortunately, that appears to be impossible currently due to restrictions that KA is putting on access to the source. Information about installing the KA back end is available at: http://khanspeak.tumblr.com/ and there used to be stuff at https://sites.google.com/a/khanacademy.org/forge/home. We have a version of this, modified to "skin" for OpenDSA, installed at /home/algoviz-beta/OpenDSA/stableExp. But you can only see it running when we turn on the server. We have abandoned this approach for now, and have developed our django-based approach instead.

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 msysgit bash shell that comes with the Git distribution.

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 Bash 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://algoviz.org/algoviz-wiki/index.php/The_OpenDSA_Developer%27s_Getting_Started_Guide"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox