From d8a820682f5d094018ee8d9153d9398b6f217fb3 Mon Sep 17 00:00:00 2001 From: Nic Ma Date: Fri, 27 May 2022 14:42:17 +0800 Subject: [PATCH 1/3] [DLMED] add to doc Signed-off-by: Nic Ma --- CONTRIBUTING.md | 19 +++++++++++++++++++ docs/source/installation.md | 2 +- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 129a839fd7..77e01be5ba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,6 +5,7 @@ 1. [Unit testing](#unit-testing) 1. [Building the documentation](#building-the-documentation) 1. [Automatic code formatting](#automatic-code-formatting) + 1. [Involve new package](#involve-new-package) 1. [Signing your work](#signing-your-work) 1. [Utility functions](#utility-functions) 1. [Backwards compatibility](#backwards-compatibility) @@ -171,6 +172,24 @@ The first line of the comment must be `/black` so that it will be interpreted by - [Auto] After the formatting commit, the GitHub action adds an emoji to the comment that triggered the process. - Repeat the above steps if necessary. +#### Involve new package +Except for `torch` and `numpy`, all the other packages are `optional import` for MONAI. All the existing optional packages are listed in [install dependencies](https://docs.monai.io/en/stable/installation.html#installing-the-recommended-dependencies). + +Sample code of import logic: +```py +from monai.utils import min_version, optional_import + +IgniteEngine, _ = optional_import("ignite.engine", 0.4.8, min_version, "Engine") + + +class Workflow(IgniteEngine): + ... +``` +To involve and config a new optional package in a pull request, please add the necessary information to below files: +[setup.cfg](https://github.com/Project-MONAI/MONAI/blob/dev/setup.cfg), [docs/requirements.txt](https://github.com/Project-MONAI/MONAI/blob/dev/docs/requirements.txt), [requirements-dev.txt](https://github.com/Project-MONAI/MONAI/blob/dev/requirements-dev.txt), [environment-dev.yml](https://github.com/Project-MONAI/MONAI/blob/dev/environment-dev.yml), [installation.md](https://github.com/Project-MONAI/MONAI/blob/dev/docs/source/installation.md), [deviceconfig.py]https://github.com/Project-MONAI/MONAI/blob/dev/monai/config/deviceconfig.py. + +Usually, developer can search `pandas` in the above files as reference to add the new content. + #### Signing your work MONAI enforces the [Developer Certificate of Origin](https://developercertificate.org/) (DCO) on all pull requests. All commit messages should contain the `Signed-off-by` line with an email address. The [GitHub DCO app](https://github.com/apps/dco) is deployed on MONAI. The pull request's status will be `failed` if commits do not contain a valid `Signed-off-by` line. diff --git a/docs/source/installation.md b/docs/source/installation.md index 76c9166566..66d9692303 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -11,7 +11,7 @@ 3. [Validating the install](#validating-the-install) 4. [MONAI version string](#monai-version-string) 5. [From DockerHub](#from-dockerhub) -6. [Installing the recommended dependencies](#Installing-the-recommended-dependencies) +6. [Installing the recommended dependencies](#installing-the-recommended-dependencies) --- From bd7c27798c94d91a10c7a11fe73d5251cfac4246 Mon Sep 17 00:00:00 2001 From: Nic Ma Date: Fri, 27 May 2022 15:09:23 +0800 Subject: [PATCH 2/3] [DLMED] add min tests Signed-off-by: Nic Ma --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77e01be5ba..e710001511 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -185,6 +185,8 @@ IgniteEngine, _ = optional_import("ignite.engine", 0.4.8, min_version, "Engine") class Workflow(IgniteEngine): ... ``` +If any of the newly added test program depends on the optional packages, please add it to the `exclude cases` of [min_tests](https://github.com/Project-MONAI/MONAI/blob/dev/tests/min_tests.py) to skip the minimal testing for it. + To involve and config a new optional package in a pull request, please add the necessary information to below files: [setup.cfg](https://github.com/Project-MONAI/MONAI/blob/dev/setup.cfg), [docs/requirements.txt](https://github.com/Project-MONAI/MONAI/blob/dev/docs/requirements.txt), [requirements-dev.txt](https://github.com/Project-MONAI/MONAI/blob/dev/requirements-dev.txt), [environment-dev.yml](https://github.com/Project-MONAI/MONAI/blob/dev/environment-dev.yml), [installation.md](https://github.com/Project-MONAI/MONAI/blob/dev/docs/source/installation.md), [deviceconfig.py]https://github.com/Project-MONAI/MONAI/blob/dev/monai/config/deviceconfig.py. From 1230cc55927fffeb5768a5f06b6dd0c991024f9c Mon Sep 17 00:00:00 2001 From: Wenqi Li Date: Fri, 27 May 2022 21:03:40 +0100 Subject: [PATCH 3/3] update docs Signed-off-by: Wenqi Li --- CONTRIBUTING.md | 48 +++++++++++++++++++++++++++---------- docs/source/installation.md | 2 +- 2 files changed, 36 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e710001511..ac373bad75 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ 1. [Unit testing](#unit-testing) 1. [Building the documentation](#building-the-documentation) 1. [Automatic code formatting](#automatic-code-formatting) - 1. [Involve new package](#involve-new-package) + 1. [Adding new optional dependencies](#adding-new-optional-dependencies) 1. [Signing your work](#signing-your-work) 1. [Utility functions](#utility-functions) 1. [Backwards compatibility](#backwards-compatibility) @@ -172,25 +172,47 @@ The first line of the comment must be `/black` so that it will be interpreted by - [Auto] After the formatting commit, the GitHub action adds an emoji to the comment that triggered the process. - Repeat the above steps if necessary. -#### Involve new package -Except for `torch` and `numpy`, all the other packages are `optional import` for MONAI. All the existing optional packages are listed in [install dependencies](https://docs.monai.io/en/stable/installation.html#installing-the-recommended-dependencies). +#### Adding new optional dependencies +In addition to the minimal requirements of PyTorch and Numpy, MONAI's core modules are built optionally based on 3rd-party packages. +The current set of dependencies is listed in [installing dependencies](https://docs.monai.io/en/stable/installation.html#installing-the-recommended-dependencies). -Sample code of import logic: +To allow for flexible integration of MONAI with other systems and environments, +the optional dependency APIs are always invoked lazily. For example, ```py -from monai.utils import min_version, optional_import +from monai.utils import optional_import +itk, _ = optional_import("itk", ...) -IgniteEngine, _ = optional_import("ignite.engine", 0.4.8, min_version, "Engine") - - -class Workflow(IgniteEngine): +class ITKReader(ImageReader): ... + def read(self, ...): + return itk.imread(...) +``` +The availability of the external `itk.imread` API is not required unless `monai.data.ITKReader.read` is called by the user. +Integration tests with minimal requirements are deployed to ensure this strategy. + +To add new optional dependencies, please communicate with the core team during pull request reviews, +and add the necessary information (at least) to the following files: +- [setup.cfg](https://github.com/Project-MONAI/MONAI/blob/dev/setup.cfg) (for package's `[options.extras_require]` config) +- [docs/requirements.txt](https://github.com/Project-MONAI/MONAI/blob/dev/docs/requirements.txt) (pip requirements.txt file) +- [environment-dev.yml](https://github.com/Project-MONAI/MONAI/blob/dev/environment-dev.yml) (conda environment file) +- [installation.md](https://github.com/Project-MONAI/MONAI/blob/dev/docs/source/installation.md) (documentation) + +When writing unit tests that use 3rd-party packages, it is a good practice to always consider +an appropriate fallback default behaviour when the packages are not installed in +the testing environment. For example: +```py +from monai.utils import optional_import +plt, has_matplotlib = optional_import("matplotlib.pyplot") + +@skipUnless(has_matplotlib, "Matplotlib required") +class TestBlendImages(unittest.TestCase): ``` -If any of the newly added test program depends on the optional packages, please add it to the `exclude cases` of [min_tests](https://github.com/Project-MONAI/MONAI/blob/dev/tests/min_tests.py) to skip the minimal testing for it. +It skips the test cases when `matplotlib.pyplot` APIs are not available. + +Alternatively, add the test file name to the ``exclude_cases`` in `tests/min_tests.py` to completely skip the test +cases when running in a minimal setup. -To involve and config a new optional package in a pull request, please add the necessary information to below files: -[setup.cfg](https://github.com/Project-MONAI/MONAI/blob/dev/setup.cfg), [docs/requirements.txt](https://github.com/Project-MONAI/MONAI/blob/dev/docs/requirements.txt), [requirements-dev.txt](https://github.com/Project-MONAI/MONAI/blob/dev/requirements-dev.txt), [environment-dev.yml](https://github.com/Project-MONAI/MONAI/blob/dev/environment-dev.yml), [installation.md](https://github.com/Project-MONAI/MONAI/blob/dev/docs/source/installation.md), [deviceconfig.py]https://github.com/Project-MONAI/MONAI/blob/dev/monai/config/deviceconfig.py. -Usually, developer can search `pandas` in the above files as reference to add the new content. #### Signing your work MONAI enforces the [Developer Certificate of Origin](https://developercertificate.org/) (DCO) on all pull requests. diff --git a/docs/source/installation.md b/docs/source/installation.md index 66d9692303..393205cd1b 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -50,7 +50,7 @@ python -c "import monai; print(monai.__version__); print(monai.__commit_id__)" ## From conda-forge -To install the [current milestone release](https://pypi.org/project/monai/): +To install the [current milestone release](https://anaconda.org/conda-forge/monai): ```bash conda install -c conda-forge monai ```