HACKING.txt

===================
Developing for ajja
===================

Installation::

  $ npm install
  $ grunt

To run tests in a browser, run::

  $ grunt test

To run tests in phantomjs, run::

  $ grunt phantomjs


Documentation
=============

The documentation is written in Sphinx and located under doc. There is a
Makefile that helps you generate the documentation from the sources. You'll
need to install sphinx globally or adjust the path inside the Makefile to your
needs.

Build the documentation with::

    $ git submodule update --init --recursive
    $ cd docs && make html
    $ open index.html

You can install the Sphinx package in your site packages or virtual environment
using pip::

    $ pip install -r docs/requirements.txt


You can make a JavaScript code block executable by giving it a label, i.e.

    .. _name-of-label:

    .. code-block:: javascript

        var foobar;

If marked this way the code block will be follow by a button labelled "Run",
which executes the JavaScript. (AJAX calls of ajja are mocked.
Also, a #form placeholder is provided.)


Releases
========

  * Run `grunt bump` or `grunt bump:major` to increase version.
  * Update Changelog (e.g. remove "unreleased").
  * Run `grunt run:docs` to build documentation for this new release.
  * Upload to readthedocs. (XXX How???)
  * Commit changes to github.
  * Create a tag for the current version:
        * git tag -a X.X.X -m "Version X.X.X"
        * git push origin X.X.X
  * Run `grunt bump:prerelase`.