Simplify test and development workflow based on tox.
@@ -21,68 +21,50 @@ Before code is pulled into the master jsonpickle branch, all tests should pass.
If you are contributing an addition or a change in behavior, we ask that you
document the change in the form of test cases.
-The jsonpickle test suite uses several JSON encoding libraries as well as
-several libraries for sample objects. To simplify the process of setting up
-these libraries we recommend creating a virtualenv_ and using a pip_
-requirements file to install the dependencies. In the base jsonpickle
-directory::
+The test suite is most readily run with the tox_ testing tool.
+Once installed, run the test suite against the default Python::
- # create a virtualenv that is completely isolated from the
- # site-wide python install
- virtualenv --no-site-packages env
+.. _tox: https://tox.readthedocs.io/
- # use pip to install development and testing dependencies
- ./env/bin/pip install --upgrade -r requirements-dev.txt
+ tox
-To run the suite, simply invoke :file:`tests/runtests.py`::
+It is recommended that you install at least one Python2 and one Python3
+interpreter for use by tox_. To test against Python 2.7 and 3.7::
- $ ./env/bin/python tests/runtests.py
- test_None (util_tests.IsPrimitiveTestCase) ... ok
- test_bool (util_tests.IsPrimitiveTestCase) ... ok
- test_dict (util_tests.IsPrimitiveTestCase) ... ok
- test_float (util_tests.IsPrimitiveTestCase) ... ok
- ...
+ tox -e py27,py37
-.. _virtualenv: http://pypi.python.org/pypi/virtualenv
-.. _pip: http://pypi.python.org/pypi/pip
+The jsonpickle test suite uses several JSON encoding libraries as well as
+several libraries for sample objects. To create an environment to test
+against these libs::
-Testing with Tox
-================
-jsonpickle supports many versions of Python. To make it easy to test
-mutiple versions of Python you should install the tox_ testing tool,
-e.g. on Debian::
+ tox -e libs
- $ sudo apt-get install tox
+To test against these libs on Python 3.7::
-Once tox_ is installed you can run the test suite against multiple Python
-interpreters::
+ tox -e py37-libs
- $ make tox
+To create the enivornment without running tests::
-It is recommended that you install at least one Python2 and one Python3
-interpreter for use by tox_.
+ tox -e libs --notest
+
+Now you may experiment and interact with jsonpickle under development
+from the virtualenv at ``.tox/libs/{bin/Scripts}/python``.
-.. _tox: https://tox.readthedocs.io/
Generate Documentation
======================
-You do not need to generate the documentation_ when contributing, though, if
-you are interested, you can generate the docs yourself. The following requires
-Sphinx_ (present if you follow the virtualenv instructions above)::
+Generating the documentation_ is not necessary when contributing.
+To build the docs::
- # pull down the sphinx-to-github project
- git submodule init
- git submodule update
+ tox -e docs
- cd docs
- make html
+Now docs are available in ``build/html``.
-If you wish to browse the documentation, use Python's :mod:`SimpleHTTPServer`
+If you wish to browse the documentation, use Python's :mod:`http.server`
to host them at http://localhost:8000::
- cd build/html
- python -m SimpleHTTPServer
+ python -m http.server -d build/html
.. _documentation: http://jsonpickle.github.com
.. _Sphinx: http://sphinx.pocoo.org
