From a3e8636a4d208e6dfbcfef3816a804f825c55802 Mon Sep 17 00:00:00 2001 From: Lance Kavalsky Date: Thu, 31 Mar 2022 15:25:09 -0400 Subject: [PATCH] update readme and contributing --- CONTRIBUTING.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 41 +++++++++++++++--- 2 files changed, 143 insertions(+), 6 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..2e81144a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,108 @@ +# Contributing + + + +- [Installation and Development](#install) + - [Running Tests](#tests) + - [Test Coverage](#test-coverage) +- [Coding Style](#codestyle) +- [PR Submission](#pr) +- [Documentation](#documentation) + +## Installation and Development + +Clone from github: +```bash +git clone https://github.com/aced-differentiate/auto_cat.git +``` + +Create a virtual environment; +one option is to use conda, but it is not required: +```bash +conda create -n python=3.9 +conda activate +``` + +Then install requirements from within the cloned `AutoCat` directory: +```bash +pip install -U -r requirements.txt +pip install -U -r test_requirements.txt +pip install --no-deps -e . +``` + +### Running tests +We use [pytest](https://docs.pytest.org/en/stable/contents.html) to run tests. +To run all tests: +```bash +pytest -svv +``` + +### Test coverage + +We use [pytest-cov](https://pytest-cov.readthedocs.io/en/latest) to check +code coverage. +To run all tests and output a report of the coverage of the `src` directory: +```bash +pytest --cov=src/ --cov-report term-missing -svv +``` + +## Coding Style + +`AutoCat` follows [PEP8](https://www.python.org/dev/peps/pep-0008/), with +several docstring rules relaxed. +See `tox.ini` for a list of the ignored rules. +Docstrings must follow the +[Numpy style](https://numpydoc.readthedocs.io/en/latest/format.html). + +We use [flake8](https://flake8.pycqa.org/en/latest/) as a linter. +To run the linter on the `src` directory: +```bash +flake8 src +``` + +A pre-commit hook is available to auto-format code with +[black](https://black.readthedocs.io/en/stable) (recommended): + +1. Make sure you are using a Python version >=3.9 +2. Install black: ``$ pip install black`` +3. Install pre-commit: ``$ pip install pre-commit`` +4. Intall git hooks in your ``.git`` directory: ``$ pre-commit install`` + +Names for functions, arguments, classes, and methods should be as descriptive as possible, +even if it means making them a little longer. For example, `generate_surface_structures` is +a preferred function name to `gen_surfs`. +All class names should adhere to [upper CamelCase](https://en.wikipedia.org/wiki/Camel_case). + +## PR Submission + +All PRs must be submitted to the `develop` branch (either fork or clone). +Releases will be from the `master` branch. + +In order to be merged, a PR must be approved by one authorized user and the +build must pass. +A passing build requires the following: +* All tests pass +* The linter finds no violations of PEP8 style (not including the exceptions in `tox.ini`) +* Every line of code is executed by a test (100% coverage) +* Documentation has been updated or extended (as needed) and builds + +PR descriptions should describe the motivation and context of the code changes in the PR, +both for the reviewer and also for future developers. If there's a Github issue, the PR should +be linked to the issue to provide that context. + +## Documentation +`AutoCat` documentation is built using `mkdocs` via +[`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/) +and +[`mkdocstrings`](https://mkdocstrings.github.io/). +All custom documentation should be written as `.md` files, appropriately placed within +`docs/`, and referenced within the `mkdocs.yml` file. + +With `mkdocs` the docs webpage can be hosted locally with the command: +```bash +mkdocs serve +``` +which will give an `html` link that can be pasted in a web-browser. + +API documentation is automatically generated with `mkdocstrings` which parses the docstrings. +Please ensure that all docstrings follow the Numpy style. diff --git a/README.md b/README.md index 7b82ca84..9721f801 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,38 @@ -# autocat -Tools for automated structure generation of catalyst systems. +# AutoCat -Currently writes out all structures as ASE trajectory files which may be read using ASE as follows: -```python -from ase.io import read +AutoCat is a suite of python tools for **sequential learning for materials applications** +and **automating structure generation for DFT catalysis studies.** -sys = read('name_of_traj.traj') +Development of this package stems from [ACED](https://www.cmu.edu/aced/), as part of the +ARPA-E DIFFERENTIATE program. + +## Installation + +There are two options for installation, either via `pip` or from the repo directly. + +### `pip` (recommended) + +If you are planning on strictly using AutoCat rather than contributing to development, + we recommend using `pip` within a virtual environment (e.g. + [`conda`](https://docs.conda.io/en/latest/) + ). This can be done +as follows: + +``` +pip install autocat +``` + +### Github (for developers) + +Alternatively, if you would like to contribute to the development of this software, +AutoCat can be installed via a clone from Github. First, you'll need to clone the +github repo to your local machine (or wherever you'd like to use AutoCat) using +`git clone`. Once the repo has been cloned, you can install AutoCat as an editable +package by changing into the created directory (the one with `setup.py`) and installing +via: +``` +pip install -e . ``` +## Contributing +Contributions through issues, feature requests, and pull requests are welcome. +Guidelines are provided [here](CONTRIBUTING.MD). \ No newline at end of file