Developing Obviel

Here is some information on how we develop Obviel and how you could participate.

Please talk to us our on our mailing list about your plans!

Sources

Obviel’s source code is maintained on bitbucket: http://bitbucket.org/obviel/obviel

You can check it out using Mercurial (hg); see the bitbucket documentation for more information as well.

Feel free to fork Obviel on bitbucket if you want to hack on it, and send us a pull request when you want us to merge your improvements.

Running the tests

The Obviel tests use Buster.JS, a powerful test runner that can run a complete browser test suite from the command line.

To run the tests you need to install Buster.JS as a Node.js module. See the Buster.JS getting started tutorial for more information. You can ignore the part about creating a config file to the project and below, as Obviel already has a config file.

In addition to installing Buster.JS, you also need to install buster-lint, an extension, into the Obviel project directory, like this:

$ npm_install buster-lint

Now to run the tests you first need to set a buster server. You do this in Obviel’s project directory:

$ buster server

It will mention starting a test server on http://localhost:1111

Go there and capture your browser as a test slave to the buster server. You can also connect more than one browser if you want, to run the tests in different browser environments.

Now on a different terminal you can run the tests, again in Obviel’s project directory:

$ buster test

Note that the Obviel test configuration also has integration with JSHint, so that any JSHint issues in your code will be automatically reported too.

Modifying the tests

The tests are maintained in the test directory under the src directory. If you want to modify the tests you should read up on Buster.JS as well as Sinon.JS (mocks for JavaScript).

Building the documentation

Obviel’s documentation is written using restructured text and Sphinx.

To build the documentation of Obviel you need Python 2.6 or Python 2.7. First you need to install buildout, a tool that installs some useful scripts for us. In the Obviel project directory, type the following:

$ python bootstrap.py -d
$ bin/buildout

After you’ve done this once, you can build the documentation using Sphinx:

$ bin/sphinxbuilder

The docs source is in doc, the built documentation will be available in doc/_build/html.

Note that the src directory in its entirety is also copied into the documentation tree under _static. This is done to make it easy to publish demo code as part of the website.