Contribute to QuantEcon.py

If you would like to contribute to QuantEcon.py, a good place to start is the project issue tracker.

Set up a development environment

We recommend developing QuantEcon.py inside an isolated environment, so that you can work against your development version of the package without disturbing the Python environment your other work depends on.

The repository ships a conda environment.yml (named qe) that contains the scientific stack along with the development tools (pytest, flake8 and flit). To clone the repository and create and activate the environment:

git clone https://github.com/QuantEcon/QuantEcon.py
cd QuantEcon.py
conda env create -f environment.yml
conda activate qe

QuantEcon.py uses flit as its build backend. Install your development copy in editable mode so that changes to the source are picked up immediately:

flit install --symlink

You can learn more about managing conda environments here.

Write tests

All functions and methods contributed to QuantEcon.py should be paired with tests to verify that they are functioning correctly.

Run the test suite with pytest:

pytest quantecon/

We also check code style with flake8. To run the same checks as continuous integration:

flake8 --select=F401,F405,E231 quantecon

Write documentation

We try to maintain a simple and consistent format for inline documentation, known in the Python world as docstrings.

The format we use is known as numpydoc.

It was developed by the numpy and scipy teams and is used in many popular packages.

Adhering to this standard helps us

  • Provide a sense of consistency throughout the library

  • Give users instant access to necessary information at the interpreter prompt (either via the built-in Python function help(object_name) or the Jupyter object_name?)

  • Easily generate a reference manual using sphinx’s autodoc and apidoc

It is always useful to build the docs locally before opening a pull request, so that you can check how your docstrings render in HTML. The documentation is built with Sphinx:

pip install -r docs/rtd-requirements.txt
cd docs
make html

The rendered pages are written to docs/build/html. Once you open a pull request, a preview of the documentation is also built automatically by Read the Docs and linked from the pull request checks.

Further questions

We encourage you to reach out to the QuantEcon team on the Discourse forum if you have any further questions.