Contributing

1. Install Development Build

From a command line, execute the following commands:

git clone https://github.com/MSDLLCpapers/obsidian
cd obsidian
git checkout main
pip install -e .[dev]

2. Style

Linting is enforced with flake8 based on configurations in .flake8.

We recommend using VS Code with flake8 extensions to automatically aid adherence to code style.

All function and method signatures should contain Python 3.10+ type hints.

Each module, class, method, and function should have a docstring. We use Google style docstrings.

We prefer that class docstrings be written under class definition instead of __init__.

3. Documentation

For documentation building, obsidian uses sphinx with autodoc and autosummary

In order to rebuild documentation, first be sure to have installed the documentation build

pip install -e .[docs]

The perform the following steps:

cd obsidian/docs
make clean
make html

Documentation HTML output will be built in obsidian/docs/build with the homepage at build/html/index.html.

Guidance Documentation

New or major changes to subpackages or modules (e.g. acquisition, surrogate, optimizer.BO_optimizer, objectives.scalarize) should be covered by informative documentation detailing API usage in Wiki articles.

Major features or configurations should be documented as examples in Tutorial notebooks.

4. Testing

For testing, obsidian uses pytest.

In order to run pytests, execute the following commands:

cd obsidian
pytest > logs/pytest_output.txt

By default, code coverage reports will be generated in logs/pytestCovReport according to configurations pytest.ini and .coveragerc. Logs will be output to logs/pytest_output.txt.

We have also enabled fast testing with majority coverage and flagged slow tests that can be avoided until major pull requests.

pytest -m fast
pytest -m "not slow"

All new features should be fully covered by newly written pytests.

5. License

By contributing to obsidian, you agree that your contributions will be licensed under the package LICENSE.