For Developers

If you would like to contribute to virtualenvwrapper directly, theseinstructions should help you get started. Patches, bug reports, andfeature requests are all welcome through the BitBucket site. Contributionsin the form of patches or pull requests are easier to integrate andwill receive priority attention.

Note

Before contributing new features to virtualenvwrapper core, pleaseconsider whether they should be implemented as an extension instead.

Building Documentation

The documentation for virtualenvwrapper is written in reStructuredTextand converted to HTML using Sphinx. The build itself is driven bymake. You will need the following packages in order to build thedocs:

  • Sphinx
  • docutils
  • sphinxcontrib-bitbucketOnce all of the tools are installed into a virtualenv usingpip, run make html to generate the HTML version of thedocumentation:
  1. $ make html
  2. rm -rf virtualenvwrapper/docs
  3. (cd docs && make html SPHINXOPTS="-c sphinx/pkg")
  4. sphinx-build -b html -d build/doctrees  -c sphinx/pkg source build/html
  5. Running Sphinx v0.6.4
  6. loading pickled environment... done
  7. building [html]: targets for 2 source files that are out of date
  8. updating environment: 0 added, 2 changed, 0 removed
  9. reading sources... [ 50%] command_ref
  10. reading sources... [100%] developers
  11.  
  12. looking for now-outdated files... none found
  13. pickling environment... done
  14. checking consistency... done
  15. preparing documents... done
  16. writing output... [ 33%] command_ref
  17. writing output... [ 66%] developers
  18. writing output... [100%] index
  19.  
  20. writing additional files... search
  21. copying static files... WARNING: static directory '/Users/dhellmann/Devel/virtualenvwrapper/plugins/docs/sphinx/pkg/static' does not exist
  22. done
  23. dumping search index... done
  24. dumping object inventory... done
  25. build succeeded, 1 warning.
  26.  
  27. Build finished. The HTML pages are in build/html.
  28. cp -r docs/build/html virtualenvwrapper/docs

The output version of the documentation ends up in./virtualenvwrapper/docs inside your sandbox.

Running Tests

The test suite for virtualenvwrapper uses shunit2 and tox. Theshunit2 source is included in the tests directory, but tox must beinstalled separately (pip install tox).

To run the tests under bash, zsh, and ksh for Python 2.7 through 3.6,run tox from the top level directory of the hg repository.

To run individual test scripts, use a command like:

  1. $ tox tests/test_cd.sh

To run tests under a single version of Python, specify the appropriateenvironment when running tox:

  1. $ tox -e py27

Combine the two modes to run specific tests with a single version ofPython:

  1. $ tox -e py27 tests/test_cd.sh

Add new tests by modifying an existing file or creating new script inthe tests directory.

Creating a New Template

virtualenvwrapper.project templates work like virtualenvwrapperplugins.The entry point group name isvirtualenvwrapper.project.template. Configure your entry point torefer to a function that will run (source hooks are not supportedfor templates).

The argument to the template function is the name of the project beingcreated. The current working directory is the directory created tohold the project files ($PROJECT_HOME/$envname).

Help Text

One difference between project templates and other virtualenvwrapperextensions is that only the templates specified by the user are run.The mkproject command has a help option to give the user a list ofthe available templates. The names are taken from the registeredentry point names, and the descriptions are taken from the docstringsfor the template functions.