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 modulesbuild.sh
builds any output assets such as pythonwhl
files or bundled javascript applicationstest.sh
executes any tests such as withpytest
for Python orjest
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.
Untested with Windows.
Mathy uses bash
scripts to set up and build its various projects. Running on windows may be complicated by this, but the scripts are simple enough to be ported.
If you are interested in doing this work, open an issue here or submit a PR.
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.