Test Environment Setup

Python-Markdown uses nose and tox for tests. Tox allows the nose tests to easily be run in all supported versions of Python. For that to work, all supported versions of Python need to be installed on the system. Then the testing tools need to be installed.

These instructions assume a typical Ubuntu Linux system.

Installing Multiple Python Versions

The simplest approach is to install from source into /opt. Apparently, /opt is where one would install optional packages. Additionally, by installing from source with the changed location, each Python version would be completely contained within a directory within /opt. If one ever wants to remove a version, all one needs to do is delete that directory and any associated links.

The first step is to ensure that all dependencies are installed for the currently installed Python version. Run the following once:

$ python --version
Python 2.7.2+
$ sudo apt-get build-dep python2.7

That will install a bunch of dev packages. Which packages get installed will likely depend of each specific system.

The following commands will need to be repeated for each version of Python not already installed. Be sure to replace the X's with the appropriate version numbers. The various versions and download links can be found on the Python download page.

$ wget http://python.org/ftp/python/X.X.X/Python-X.X.X.tgz
$ tar xvfz Python-X.X.X.tgz
$ cd Python-X.X.X
$ ./configure --prefix=/opt/pythonX.X
$ make
$ sudo make install

Of course, these need to be on the path to be useful so create some links:

$ sudo ln -s /opt/pythonX.X/bin/pythonX.X /usr/bin/pythonX.X

While Python-Markdown no longer uses the 2to3 conversion tool, it may be helpful anyway:

$ sudo ln -s /opt/python3.3/bin/2to3 /usr/bin/2to3

It is recommended that 2to3 only be linked once for the most recent version. It's not likely needed for every version of Python.

Installing the Testing Tools

Once all the Python versions are installed, the tools used to run the tests need to be installed. However, then will only need to be installed for the system's default Python version as virtual environments will be created by tox to run the tests in.

If they're not already installed, download and install virtualenv's dependencies:

$ wget http://python-distribute.org/distribute_setup.py
$ sudo python distribute_setup.py
$ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
$ sudo python get-pip.py

Now, use pip to install virtualenv and tox:

$ sudo pip install virtualenv
$ sudo pip install tox

As tox will install nose in the test virtual environments it creates, nose does not need to be installed globally. However, during development, it may be helpful to quickly run tests in only one environment as one iterates through small changes. Therefore, it is suggested that a development environment be created that includes an installation of nose. To more easily work with the environment, virtualenvwrapper can be helpful.

$ sudo pip install virtualenvwrapper

Then configure virtualenvwrapper as instructed in the docs. At a minimum, add the following lines to ~/.profile or ~/.bashrc

export VIRTUALENV_DISTRIBUTE=true    
export WORKON_HOME=$HOME/.virtualenvs
source /usr/local/bin/virtualenvwrapper.sh

After saving and sourcing that file (eg: source .profile), then create an environment:

$ mkvirtualenv md
(md)$ pip install nose

Run the Tests

Now that everything is set up, the tests can be run. First a copy of the source needs to be cloned from Github:

$ git clone git@github.com:<username>/Python-Markdown.git md

Be sure to replace "<username>" above with our own username. You are cloning from your own fork right? How else will you create pull requests to get your changes committed upstream?

If the development virtual environment created earlier isn't active, activate it and run the tests in the default Python version:

$ cd md
$ workon md
(md)$ ./run-tests.py

Now that the development environment is working, deactivate it, and run tox:

(md)$ deactivate
$ tox

The first time it runs, tox will take a bit longer as it needs to create each virtual environment. However, in the future, the test environments will already exist, so the tests will run more quickly.