Thank you for your interest in contributing to mat_discover! We're glad you found this resource, and we hope it will be of use to you.
We welcome any contributions you might be willing to add, including suggestions, reporting bugs, or contributions to the codebase.
For feature requests and reporting bugs, please open a GitHub issue.
This project was developed primarily in Python in Visual Studio Code using black, mypy,
pydocstyle, kite, other tools, and various community extensions. Some other notable tools used in this project are:
- Miniconda (fewer issues during Python development than Anaconda with minimal downsides)
pipreqswas used as a starting point forrequirements.txtflitis used as a starting point forpyproject.toml, to perform local installation, and to publish to PyPIconda env export --from-history -f environment.ymlwas used as a starting point forenvironment.ymlgrayskullandconda-souschefare used to generate and tweakmeta.yaml, respectively, for publishing to Anaconda. See thisconda-souschefissue for additional details.- A variety of GitHub actions are used (see workflows)
pytestis used for testingnumbais used to accelerate the Wasserstein distance matrix computations via CPU or GPU (which now happens in the external dependency,chem_wassersteinviadist-matrixpackage).
For simple changes (e.g. quick-fix in documentation), navigate to https://github.com/sparks-baird/mat_discover, click on the
relevant file (e.g. README.md), and look for the pencil (✏️). GitHub will walk you through the rest.
This goes over installation and, if desired, VS Code Settings Sync.
To help with development, we suggest that you install from source. Note that when using a conda environment
(recommended), you may avoid certain issues down the road by opening VS Code via an
Anaconda command prompt and entering the command code (at least until the VS Code devs
fix some of the issues associated with opening it "normally"). For example, in Windows,
press the "Windows" key, type "anaconda", and open "Anaconda Powershell Prompt
(miniconda3)" or similar. Then type code and press enter.
The most seamless install that is least likely to cause issues will be using flit. For example, starting from the top:
git clone https://github.com/sparks-baird/mat_discover.git
cd mat_discover
conda create -n python==3.9.*
conda install flit
flit install --pth-fileFrom the flit docs:
--pth-fileCreate a.pthfile in site-packages rather than copying the module, so you can test changes without reinstalling. This is a less elegant alternative to--symlink, but it works on Windows, which typically doesn’t allow symlinks.
This should ensure that your setup is similar to the one used for development and testing. flit is also used to publish new PyPI versions
and to prep metadata for grayskull which creates conda recipes that are used to publish to Anaconda. Additionally, you may find it useful to use my
"secret sauce" list of VS Code extensions and settings by using the Settings Sync
extension and inputting the GitHub Gist ID (98ade0073783c7dd54c50d5c8105d07d)
for my Settings Sync file when asked. You can keep it up-to-date with my settings, use these as a starting point
(by disconnecting Settings Sync or removing the Gist ID after the initial download and sync), or pick and choose from the list as you see fit.
By no means is it required, but these have made the Python development experience a lot more enjoyable for me.
To build the docs, if you did a local installation via flit install --pth-file, you can ignore the following installation steps.
Ensure that sphinx, sphinx_rtd_theme, and sphinx_copy_button are installed:
conda install sphinx sphinx_rtd_theme sphinx_copy_buttonAlternatively, make sure all files from requirements.txt are installed:
conda install --file requirements.txtThen run:
cd docs/
make htmlOpen docs/build/index.html (e.g. via start build/index.html on Windows, or by clicking on index.html in a file browser)
to view the documentation on your internet browser (e.g. Google Chrome).