<commit_before>Developing Obviel
=================

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

Please talk to us our on our :ref:`mailing list <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.

.. _`Mercurial`: http://mercurial.selenic.com/

.. _`bitbucket`: http://bitbucket.org

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 run in a web browser.

Accessing the tests
~~~~~~~~~~~~~~~~~~~

You can access Obviel's tests by constructing a ``file:`` URL
to the test page. For instance:

file:///home/faassen/projects/obviel/src/test/index.html

You can also access Obviel's tests through a web server. This is
useful as some web browsers have test failures due to the peculiar way
``file:`` URLs are accessed. In addition, the JSCoverage tool
described below recommends against the use of ``file:`` URLs. A simple
way to start a web server is to type this in the project directory::

$ python -m SimpleHTTPServer

where ``python`` is a Python 2.x interpreter. You can then navigate
to:

http://localhost:8000/src/test

for the test page.

Executing the tests
~~~~~~~~~~~~~~~~~~~

From the test page, you will see various links to the individual test
suites:

* obviel.js tests - tests for the Obviel core

* obviel-forms.js tests - tests for Obviel forms

* JSHint - run JSHint against Obviel

There is also a section with manual (non-automatic) tests; this is
more for experimentation during development with the form logic in
particular.
 
Modifying the tests
~~~~~~~~~~~~~~~~~~~

The tests are maintained in the ``test`` directory under the ``src``
directory. They use qunit_ test engine.

.. _`qunit`: http://docs.jquery.com/Qunit

Test coverage
~~~~~~~~~~~~~

The JSCoverage_ tool can be used to analyze the test coverage: how
much of the Obviel code is being actually called from the test
suite. To use it, first create a special coverage-analysis copy of the
Obviel project directory.  If your Obviel project directory is called
``obviel``, change to the parent directory above it and type this::

  $ jscoverage obviel obviel-cov

Then go to obviel-cov and start a web server::

  $ python -m SimpleHTTPServer

Now go to the special coverage analysis page:

http://localhost:8000/jscoverage.html

In the URL input on the coverage page, type the following and press
``Open in frame``:

http://localhost:8000/src/test

Then click on the automatic test suite you want to run.

You can then click on the 'Summary' tab and see how much coverage the
test suite has for the file ``src/obviel.js``.

.. _`JSCoverage`: http://siliconforks.com/jscoverage/

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

.. _Sphinx: http://sphinx.pocoo.org/

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.

Obviel test server
------------------

We've included obvielts, which is a simple Python-based web server
that is used to test integration with dynamic server code.

To build obvielts, you need to do a buildout (if you've installed the
documentation you already will have it)::

  $ python bootstrap.py -d
  $ bin/buildout

You can now start the obvielts server using paster_:

  $ bin/paster serve parts/etc/debug.ini

It will be available here::<commit_msg>More pretty colors.<commit_after>Developing Obviel
=================

.. highlight:: console

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

Please talk to us our on our :ref:`mailing list <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.

.. _`Mercurial`: http://mercurial.selenic.com/

.. _`bitbucket`: http://bitbucket.org

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 run in a web browser.

Accessing the tests
~~~~~~~~~~~~~~~~~~~

You can access Obviel's tests by constructing a ``file:`` URL
to the test page. For instance:

file:///home/faassen/projects/obviel/src/test/index.html

You can also access Obviel's tests through a web server. This is
useful as some web browsers have test failures due to the peculiar way
``file:`` URLs are accessed. In addition, the JSCoverage tool
described below recommends against the use of ``file:`` URLs. A simple
way to start a web server is to type this in the project directory::

  $ python -m SimpleHTTPServer

where ``python`` is a Python 2.x interpreter. You can then navigate
to:

http://localhost:8000/src/test

for the test page.

Executing the tests
~~~~~~~~~~~~~~~~~~~

From the test page, you will see various links to the individual test
suites:

* obviel.js tests - tests for the Obviel core

* obviel-forms.js tests - tests for Obviel forms

* JSHint - run JSHint against Obviel

There is also a section with manual (non-automatic) tests; this is
more for experimentation during development with the form logic in
particular.
 
Modifying the tests
~~~~~~~~~~~~~~~~~~~

The tests are maintained in the ``test`` directory under the ``src``
directory. They use qunit_ test engine.

.. _`qunit`: http://docs.jquery.com/Qunit

Test coverage
~~~~~~~~~~~~~

The JSCoverage_ tool can be used to analyze the test coverage: how
much of the Obviel code is being actually called from the test
suite. To use it, first create a special coverage-analysis copy of the
Obviel project directory.  If your Obviel project directory is called
``obviel``, change to the parent directory above it and type this::

  $ jscoverage obviel obviel-cov

Then go to obviel-cov and start a web server::

  $ python -m SimpleHTTPServer

Now go to the special coverage analysis page:

http://localhost:8000/jscoverage.html

In the URL input on the coverage page, type the following and press
``Open in frame``:

http://localhost:8000/src/test

Then click on the automatic test suite you want to run.

You can then click on the 'Summary' tab and see how much coverage the
test suite has for the file ``src/obviel.js``.

.. _`JSCoverage`: http://siliconforks.com/jscoverage/

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

.. _Sphinx: http://sphinx.pocoo.org/

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.

Obviel test server
------------------

We've included obvielts, which is a simple Python-based web server
that is used to test integration with dynamic server code.

To build obvielts, you need to do a buildout (if you've installed the
documentation you already will have it)::

  $ python bootstrap.py -d
  $ bin/buildout

You can now start the obvielts server using paster_::

  $ bin/paster serve parts/etc/debug.ini

It will be available here::
{'fraction_non_alphanumeric': 0.10091416359966758, 'fraction_numerical': 0.004036566543986703, 'mean_word_length': 3.797266514806378, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '69417', 'n_tokens_mistral': 2497, 'n_tokens_neox': 2373, 'n_words': 1179}