Contributing

Project Structure¶

Mathy has several different python projects inside the libraries folder.

Each project contains a tools folder with a set of bash scripts inside for configuring and executing the tasks related to a specific project.

Each project must have at least the following:

• setup.sh does any setup such as creating virtual-environments or installing node modules
• build.sh builds any output assets such as python whl files or bundled javascript applications
• test.sh executes any tests such as with pytest for Python or jest for Javascript

Setup¶

Mathy can either build everything or specific sub-projects.

All Projects¶

From the root folder, run the tools/setup.sh script, which will install the pre-requisites for all projects in the libraries folder:

sh tools/setup.sh

One Project¶

From the root folder, change directories into the desired project folder, e.g.

cd libraries/website

From the project folder, run the setup script:

sh tools/setup.sh

Use your local version of Mathy¶

You can install the Mathy python package from the file system:

pip install -e ./libraries/mathy_python

Then use the mathy CLI directly:

mathy simplify "4x + 2y + 6x"

Code¶

If you know that you want to make a code contribution or make significant changes to the documentation site, there are bash scripts that set up and build the various parts of Mathy.

Docs¶

The documentation uses MkDocs.

All the documentation is in Markdown format in the directory ./libraries/website/docs.

Many of the pages include blocks of code that are complete, runnable applications that live in the ./libraries/website/docs/snippets/ directory.

Docs for tests¶

All of the inline python snippets double as tests run with each website build. This helps ensure that:

• The documentation is up to date.
• The documentation examples can be run as-is.
• The documentation examples can be launched in Colab.

After executing the test snippets, we convert each file to an iPython notebook and an "Open in Colab" badge is inserted near the snippet.

Having a one-click option for running code snippets allows users to launch into examples and run them directly from their browser.

During local development, there is a script that builds the site and checks for any changes, live-reloading:

cd libraries/website
sh tools/develop.sh

It will serve the documentation on http://127.0.0.1:8000.

That way, you can edit the documentation/source files and see the changes live.

Tests¶

There is a script that you can run locally to test all the code and generate coverage reports in HTML.

From the root folder, run:

sh tools/test.sh

This command generates a directory ./htmlcov/. If you open the file ./htmlcov/index.html in your browser, you can interactively explore the regions of code covered by test execution.