DOC: Add part of the API to the Sphinx docs (#718)

* Add part of the API to the Sphinx docs

* Improve layout of landing page

* Remove redundant caption

* Include all documentation in Sphinx and fix docstrings

* Remove redundant options

InnerEye/ML/augmentations/augmentation_for_segmentation_utils.py

@@ -114,8 +114,9 @@ def random_crop(sample: Sample,
     :param class_weights: A weighting vector with values [0, 1] to influence the class the center crop
                           voxel belongs to (must sum to 1), uniform distribution assumed if none provided.
     :return: Tuple item 1: The cropped images, labels, and mask. Tuple item 2: The center that was chosen for the crop,
-    before shifting to be inside of the image. Tuple item 3: The slicers that convert the input image to the chosen
-    crop.
+        before shifting to be inside of the image. Tuple item 3: The slicers that convert the input image to the chosen
+        crop.
+
     :raises ValueError: If there are shape mismatches among the arguments or if the crop size is larger than the image.
     """
     slicers, center = slicers_for_random_crop(sample, crop_size, class_weights)

InnerEye/ML/augmentations/image_transforms.py

@@ -76,6 +76,7 @@ class AddGaussianNoise:
 
 class ElasticTransform:
     """Elastic deformation of images as described in [Simard2003]_.
+
     .. [Simard2003] Simard, Steinkraus and Platt, "Best Practices for
        Convolutional Neural Networks applied to Visual Document Analysis", in
        Proc. of the International Conference on Document Analysis and

InnerEye/ML/pipelines/inference.py

@@ -239,6 +239,7 @@ class InferencePipeline(FullImageInferencePipelineBase):
                             patient_id: int = 0) -> InferencePipeline.Result:
         """
         Performs a single inference pass through the pipeline for the provided image
+
         :param image_channels: The input image channels to perform inference on in format: Channels x Z x Y x X.
         :param voxel_spacing_mm: Voxel spacing to use for each dimension in (Z x Y x X) order
         :param mask: A binary image used to ignore results outside it in format: Z x Y x X.

InnerEye/ML/pipelines/scalar_inference.py

@@ -75,6 +75,7 @@ class ScalarInferencePipeline(ScalarInferencePipelineBase):
                                pipeline_id: int = 0) -> Optional[ScalarInferencePipeline]:
         """
         Creates an inference pipeline from a single checkpoint.
+
         :param path_to_checkpoint: Path to the checkpoint to recover.
         :param config: Model configuration information.
         :param pipeline_id: ID for the pipeline to be created.
@@ -95,11 +96,12 @@ class ScalarInferencePipeline(ScalarInferencePipelineBase):
     def predict(self, sample: Dict[str, Any]) -> ScalarInferencePipelineBase.Result:
         """
         Runs the forward pass on a single batch.
+
         :param sample: Single batch of input data.
-                        In the form of a dict containing at least the fields:
-                        metadata, label, images, numerical_non_image_features,
-                        categorical_non_image_features and segmentations.
-        :return: Returns ScalarInferencePipelineBase.Result with  the subject ids, ground truth labels and predictions.
+            In the form of a dictionary containing at least the fields:
+            metadata, label, images, numerical_non_image_features,
+            categorical_non_image_features and segmentations.
+        :return: ScalarInferencePipelineBase.Result with the subject ids, ground truth labels and predictions.
         """
         assert isinstance(self.model_config, ScalarModelBase)
         model_inputs_and_labels = get_scalar_model_inputs_and_labels(self.model.model,
@@ -158,10 +160,11 @@ class ScalarEnsemblePipeline(ScalarInferencePipelineBase):
         """
         Performs inference on a single batch. First does the forward pass on all of the single inference pipelines,
         and then aggregates the results.
+
         :param sample: single batch of input data.
-                        In the form of a dict containing at least the fields:
-                        metadata, label, images, numerical_non_image_features,
-                        categorical_non_image_features and segmentations.
+            In the form of a dictionary containing at least the fields:
+            metadata, label, images, numerical_non_image_features,
+            categorical_non_image_features and segmentations.
         :return: Returns ScalarInferencePipelineBase.Result with the subject ids, ground truth labels and predictions.
         """
         results = [pipeline.predict(sample) for pipeline in self.pipelines]

sphinx-docs/source/conf.py

@@ -77,3 +77,10 @@ source_suffix = {
     '.rst': 'restructuredtext',
     '.md': 'markdown',
 }
+
+# Autodoc options
+
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+}

sphinx-docs/source/index.rst

@@ -8,7 +8,6 @@ InnerEye-DeepLearning Documentation
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contents
 
    md/README.md
    md/docs/WSL.md
@@ -19,12 +18,6 @@ InnerEye-DeepLearning Documentation
    md/docs/sample_tasks.md
    md/docs/debugging_and_monitoring.md
 
-.. toctree::
-   :maxdepth: 1
-   :caption: About Model Configs
-
-   rst/configs.rst
-
 .. toctree::
    :maxdepth: 1
    :caption: Further reading for contributors
@@ -33,6 +26,21 @@ InnerEye-DeepLearning Documentation
    md/docs/testing.md
    md/docs/contributing.md
 
+   md/docs/hello_world_model.md
+   md/docs/deploy_on_aml.md
+   md/docs/bring_your_own_model.md
+   md/docs/fastmri.md
+   md/docs/innereye_as_submodule.md
+   md/docs/model_diagnostics.md
+   md/docs/move_model.md
+   md/docs/releases.md
+   md/docs/self_supervised_models.md
+   md/CHANGELOG.md
+
+.. toctree::
+   :caption: API documentation
+
+   rst/api/index
 
 
 Indices and tables
@@ -40,4 +48,3 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`

sphinx-docs/source/rst/api/ML/augmentations.rst

@@ -0,0 +1,8 @@
+Data augmentation
+=================
+
+.. automodule:: InnerEye.ML.augmentations.augmentation_for_segmentation_utils
+
+.. automodule:: InnerEye.ML.augmentations.image_transforms
+
+.. automodule:: InnerEye.ML.augmentations.transform_pipeline

sphinx-docs/source/rst/api/ML/configs.rst

@@ -40,6 +40,4 @@ Segmentation Model Configuration
    .. autoattribute:: is_plotting_enabled
 
 .. automodule:: InnerEye.ML.config
-   :members:
-   :undoc-members:
    :exclude-members: SegmentationModelBase

sphinx-docs/source/rst/api/ML/index.rst

@@ -0,0 +1,10 @@
+Machine learning
+================
+
+.. toctree::
+
+   configs
+   runner
+   augmentations
+   photometric_normalization
+   pipelines

sphinx-docs/source/rst/api/ML/photometric_normalization.rst

@@ -0,0 +1,4 @@
+Photometric normalization
+=========================
+
+.. automodule:: InnerEye.ML.photometric_normalization

sphinx-docs/source/rst/api/ML/pipelines.rst

@@ -0,0 +1,8 @@
+Pipelines
+=========
+
+.. automodule:: InnerEye.ML.pipelines.inference
+
+.. automodule:: InnerEye.ML.pipelines.ensemble
+
+.. automodule:: InnerEye.ML.pipelines.scalar_inference

sphinx-docs/source/rst/api/ML/runner.rst

@@ -0,0 +1,4 @@
+Runner
+======
+
+.. automodule:: InnerEye.ML.runner

sphinx-docs/source/rst/api/index.rst

@@ -0,0 +1,3 @@
+.. toctree::
+
+   ML/index