Contributing to Morelia π·ββοΈο
So, you want to contribute to Morelia? Well, this is the place to be!
Setting Up a Morelia Development Enviornment π§βπο
The first step to setting up a Morelia development enviornment is to follow the βSetting Up Your Enviornmentβ section on the getting started page.
After that, clone an up to date copy of the source code repository.
Constructing a Python Environment with Anaconda π§βπ³ο
If you do not want to use Anaconda to install the project dependencies,
pip will automatically install them when we install Morelia
for development.
Therefore, this step is technically optional, but highly recommended.
Anaconda is a fantastic tool for managing Python environments
and makes setting one up for Morelia a breeze.
To get started, begin by installing Anaconda (or Miniconda) if you do not already have it. Download the installer here.
After Anaconda is installed, running the following command in the top level directory of your cloned repo downloads and sets up all the dependencies for Morelia.
conda env create -f environment.yml
Installing Morelia for Development πο
After you have cloned the source code (and hopefully set up and Anaconda environment, but again, that step is not strictly required),
the last step is to install Morelia itself for development! Currently, the way to do this is using pip to creat an editable install.
This allows us to Morelia as if it is a package installed in our environment, but the package will automatically update as we make
changes to the source code. Therefore, there is no need to reinstall Morelia each time.
To create this editable install, run the following in the top level of your repository:
pip install -e .
Running Tests π§ͺο
Building out tests for Morelia is an ongoing effort, but is done using the pytest framework.
The current tests for Morelia can be found in the tests directory. To run the tests, use the following command from the top-level
of your repository
pytest
It is worth noting there is also an old_tests folder. These scripts from a deprecated testing framework that require physical devices to
be plugged into your computer. Currently, these are still in the repository as they can be useful for in-house testing of devices or testing
some older functionality that do not yet have pytest tests written. The future of these files is uncertain, but for now they are there so
itβs probably useful to know what they are.
Building Documentation πο
Moreliaβs documentation is built using Spinx,
and the source files can be found in the docs folder. It also uses the autodoc and sphinx-autodoc-typehints extensions to automatically build documenatation for all functions and classes using docstrings.
To build the HTML documentation, simply run
make html
in the docs folder. There is no need to commit HTML documentation to GitHub, as it is
automatically built via a continuous integration (CI) pipeline when a branch is merged into integration.
Sphinx offers a bunch of other formats to output documentation in! Fell free to explore, however we only
use HTML for public facing docs.
Uploading to PyPI π¦ο
Morelia is on the Python Package Index! New versions are automatically packaged an uploaded by a GitHub Actions CI pipeline within the repo that runs every time a new tag is pushed. In order to make sure that the run succeeds, make sure that the version of the tag you pushed matches the version number in the pyproject.toml file. If these versions do not match, the run will likely fail. Specifically, if the version number is not updated, it will try to upload a version to PyPI that is already present, causing things to implode. Note that if you are not a maintainer, you will not have permissions to push a tag to GitHub.