2639 documentation for the deprecated API

CONTRIBUTING.md

@@ -7,6 +7,7 @@
  1. [Automatic code formatting](#automatic-code-formatting)
  1. [Signing your work](#signing-your-work)
  1. [Utility functions](#utility-functions)
+ 1. [Backwards compatibility](#backwards-compatibility)
  * [Submitting pull requests](#submitting-pull-requests)
 - [The code reviewing process (for the maintainers)](#the-code-reviewing-process)
  * [Reviewing pull requests](#reviewing-pull-requests)
@@ -229,6 +230,12 @@ for example, ``import monai.transforms.Spacing`` is the equivalent of ``monai.tr
 
 For string definition, [f-string](https://www.python.org/dev/peps/pep-0498/) is recommended to use over `%-print` and `format-print` from python 3.6. So please try to use `f-string` if you need to define any string object.
 
+#### Backwards compatibility
+MONAI is currently under active development, and with major version zero (following the [Semantic Versioning](https://semver.org/)).
+The backwards compatibility of the API is not always guaranteed at this initial development stage.
+However, utility functions are provided in the `monai.utils.deprecated` modules to help users migrate to the new API.
+The use of these functions is encouraged.
+
 
 ### Submitting pull requests
 All code changes to the dev branch must be done via [pull requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests).

monai/handlers/segmentation_saver.py

@@ -37,6 +37,9 @@ class SegmentationSaver:
  use index from 0 as the filename prefix.
  The predictions can be PyTorch Tensor with [B, C, H, W, [D]] shape or a list of Tensor without batch dim.
 
+ .. deprecated:: 0.6.0
+ Use :class:`monai.transforms.SaveImage` or :class:`monai.transforms.SaveImaged` instead.
+
  """
 
  def __init__(

monai/handlers/transform_inverter.py

@@ -36,6 +36,9 @@ class TransformInverter:
  And the inverted meta dict will be stored in `engine.state.batch`
  with key: "{meta_keys}" or "{key}_{meta_key_postfix}".
 
+ .. deprecated:: 0.6.0
+ Use :class:`monai.transforms.Invertd` instead.
+
  """
 
  def __init__(

monai/handlers/utils.py

@@ -68,6 +68,9 @@ def evenly_divisible_all_gather(data: torch.Tensor) -> torch.Tensor:
  Note:
  The input data on different ranks must have exactly same `dtype`.
 
+ .. versionchanged:: 0.6.0
+ The API had been moved to `monai.utils`.
+
  """
  if not isinstance(data, torch.Tensor):
  raise ValueError("input data must be PyTorch Tensor.")
@@ -98,6 +101,9 @@ def string_list_all_gather(strings: List[str]) -> List[str]:
  Args:
  strings: a list of strings to all gather.
 
+ .. versionchanged:: 0.6.0
+ The API had been moved to `monai.utils`.
+
  """
  world_size = idist.get_world_size()
  if world_size <= 1:

monai/networks/nets/dynunet_v1.py

@@ -43,6 +43,10 @@ class DynUNetV1(DynUNet):
  deep_supr_num: number of feature maps that will output during deep supervision head. Defaults to 1.
  res_block: whether to use residual connection based convolution blocks during the network.
  Defaults to ``False``.
+
+ .. deprecated:: 0.6.0
+ Use :class:`monai.networks.nets.DynUNet` instead.
+
  """
 
  def __init__(

monai/networks/nets/torchvision_fc.py

@@ -81,6 +81,10 @@ class TorchVisionFullyConvModel(TorchVisionFCModel):
  pool_size: the kernel size for `AvgPool2d` to replace `AdaptiveAvgPool2d`. Default to (7, 7).
  pool_stride: the stride for `AvgPool2d` to replace `AdaptiveAvgPool2d`. Default to 1.
  pretrained: whether to use the imagenet pretrained weights. Default to False.
+
+ .. deprecated:: 0.6.0
+ Use :class:`monai.networks.nets.TorchVisionFCModel` instead.
+
  """
 
  def __init__(

monai/utils/deprecated.py

@@ -46,6 +46,10 @@ def deprecated(
  a `DeprecatedError` exception is instead raised if `removed` is given and the current version is at or later
  than that, or if neither `since` nor `removed` is provided.
 
+ The relevant docstring of the deprecating function should also be updated accordingly,
+ using the Sphinx directives such as `.. versionchanged:: version` and `.. deprecated:: version`.
+ https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded
+
  Args:
  since: version at which the definition was marked deprecated but not removed.
  removed: version at which the definition was removed and no longer usable.
@@ -122,6 +126,11 @@ def deprecated_arg(
  a `DeprecatedError` exception is instead raised if `removed` is given and the current version is at or later
  than that, or if neither `since` nor `removed` is provided.
 
+ The relevant docstring of the deprecating function should also be updated accordingly,
+ using the Sphinx directives such as `.. versionchanged:: version` and `.. deprecated:: version`.
+ https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded
+
+
  Args:
  name: name of position or keyword argument to mark as deprecated.
  since: version at which the argument was marked deprecated but not removed.