Add API documentation (#2610)

* add api doc

* update mock modules and fix requirements

* fix autodoc modules

* remove tmp file

* add release version in docs/conf.py

* fix docstring styles

.readthedocs.yml

+version: 2
+
+python:
+    version: 3.7
+    install:
+      - requirements: requirements/docs.txt
+      - requirements: requirements/readthedocs.txt

docs/api.rst

+API Documentation
+=================
+
+mmdet.apis
+--------------
+.. automodule:: mmdet.apis
+    :members:
+
+mmdet.core
+--------------
+
+anchor
+^^^^^^^^^^
+.. automodule:: mmdet.core.anchor
+    :members:
+
+bbox
+^^^^^^^^^^
+.. automodule:: mmdet.core.bbox
+    :members:
+
+mask
+^^^^^^^^^^
+.. automodule:: mmdet.core.mask
+    :members:
+
+evaluation
+^^^^^^^^^^
+.. automodule:: mmdet.core.evaluation
+    :members:
+
+post_processing
+^^^^^^^^^^^^^^^
+.. automodule:: mmdet.core.post_processing
+    :members:
+
+fp16
+^^^^^^^^^^
+.. automodule:: mmdet.core.fp16
+    :members:
+
+optimizer
+^^^^^^^^^^
+.. automodule:: mmdet.core.optimizer
+    :members:
+
+utils
+^^^^^^^^^^
+.. automodule:: mmdet.core.utils
+    :members:
+
+mmdet.datasets
+--------------
+
+datasets
+^^^^^^^^^^
+.. automodule:: mmdet.datasets
+    :members:
+
+pipelines
+^^^^^^^^^^
+.. automodule:: mmdet.datasets.pipelines
+    :members:
+
+mmdet.models
+--------------
+
+detectors
+^^^^^^^^^^
+.. automodule:: mmdet.models.detectors
+    :members:
+
+backbones
+^^^^^^^^^^
+.. automodule:: mmdet.models.backbones
+    :members:
+
+anchor_heads
+^^^^^^^^^^^^
+.. automodule:: mmdet.models.anchor_heads
+    :members:
+
+roi_extractors
+^^^^^^^^^^^^^^
+.. automodule:: mmdet.models.roi_extractors
+    :members:
+
+roi_heads
+^^^^^^^^^^
+.. automodule:: mmdet.models.roi_heads
+    :members:
+
+bbox_heads
+^^^^^^^^^^
+.. automodule:: mmdet.models.bbox_heads
+    :members:
+
+mask_heads
+^^^^^^^^^^
+.. automodule:: mmdet.models.mask_heads
+    :members:
+
+shared_heads
+^^^^^^^^^^^^
+.. automodule:: mmdet.models.shared_heads
+    :members:
+
+losses
+^^^^^^^^^^
+.. automodule:: mmdet.models.losses
+    :members:

docs/conf.py

@@ -10,9 +10,10 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
 
@@ -21,7 +22,8 @@ copyright = '2018-2020, OpenMMLab'
 author = 'MMDetection Authors'
 
 # The full version, including alpha/beta/rc tags
-release = '1.0.0'
+with open('../mmdet/VERSION', 'r') as f:
+    release = f.read().strip()
 
 # -- General configuration ---------------------------------------------------
 
@@ -36,7 +38,12 @@ extensions = [
     'sphinx_markdown_tables',
 ]
 
-autodoc_mock_imports = ['torch', 'torchvision', 'mmcv', 'numpy', 'pycocotools']
+autodoc_mock_imports = [
+    'cv2', 'mmcv', 'matplotlib', 'pycocotools', 'terminaltables',
+    'mmdet.version', 'mmdet.ops.dcn', 'mmdet.ops.dcn', 'mmdet.ops.masked_conv',
+    'mmdet.ops.nms', 'mmdet.ops.roi_align', 'mmdet.ops.roi_pool',
+    'mmdet.ops.sigmoid_focal_loss', 'mmdet.ops.carafe', 'mmdet.ops.utils'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -14,7 +14,7 @@ Welcome to MMDetection's documentation!
    tutorials/new_modules.md
    compatibility.md
    changelog.md
-
+   api.rst
 
 
 Indices and tables

docs/requirements.txt

-recommonmark
-sphinx
-sphinx_markdown_tables
-sphinx_rtd_theme

mmdet/core/anchor/anchor_generator.py

@@ -395,6 +395,7 @@ class LegacyAnchorGenerator(AnchorGenerator):
     """Legacy anchor generator used in MMDetection V1.x
 
     Difference to the V2.0 anchor generator:
+
     1. The center offset of V1.x anchors are set to be 0.5 rather than 0.
     2. The width/height are minused by 1 when calculating the anchors' centers
        and corners to meet the V1.x coordinate system.

mmdet/core/bbox/assigners/assign_result.py

@@ -102,10 +102,9 @@ class AssignResult(util_mixins.NiceRepr):
 
     @classmethod
     def random(cls, **kwargs):
-        """
-        Create random AssignResult for tests or debugging.
+        """Create random AssignResult for tests or debugging.
 
-        Kwargs:
+        Args:
             num_preds: number of predicted boxes
             num_gts: number of true boxes
             p_ignore (float): probability of a predicted box assinged to an
@@ -116,7 +115,7 @@ class AssignResult(util_mixins.NiceRepr):
             rng (None | int | numpy.random.RandomState): seed or state
 
         Returns:
-            AssignResult :
+            :obj:`AssignResult`: Randomly generated assign results.
 
         Example:
             >>> from mmdet.core.bbox.assigners.assign_result import *  # NOQA

mmdet/core/bbox/samplers/sampling_result.py

@@ -4,7 +4,8 @@ from mmdet.utils import util_mixins
 
 
 class SamplingResult(util_mixins.NiceRepr):
-    """
+    """Bbox sampling result.
+
     Example:
         >>> # xdoctest: +IGNORE_WANT
         >>> from mmdet.core.bbox.samplers.sampling_result import *  # NOQA
@@ -52,8 +53,7 @@ class SamplingResult(util_mixins.NiceRepr):
         return torch.cat([self.pos_bboxes, self.neg_bboxes])
 
     def to(self, device):
-        """
-        Change the device of the data inplace.
+        """Change the device of the data inplace.
 
         Example:
             >>> self = SamplingResult.random()
@@ -77,9 +77,7 @@ class SamplingResult(util_mixins.NiceRepr):
 
     @property
     def info(self):
-        """
-        Returns a dictionary of info about the object
-        """
+        """Returns a dictionary of info about the object."""
         return {
             'pos_inds': self.pos_inds,
             'neg_inds': self.neg_inds,
@@ -94,19 +92,18 @@ class SamplingResult(util_mixins.NiceRepr):
     def random(cls, rng=None, **kwargs):
         """
         Args:
-            rng (None | int | numpy.random.RandomState): seed or state
-
-        Kwargs:
-            num_preds: number of predicted boxes
-            num_gts: number of true boxes
-            p_ignore (float): probability of a predicted box assinged to an
-                ignored truth
-            p_assigned (float): probability of a predicted box not being
-                assigned
-            p_use_label (float | bool): with labels or not
+            rng (None | int | numpy.random.RandomState): seed or state.
+            kwargs (keyword arguments):
+                - num_preds: number of predicted boxes
+                - num_gts: number of true boxes
+                - p_ignore (float): probability of a predicted box assinged to
+                    an ignored truth.
+                - p_assigned (float): probability of a predicted box not being
+                    assigned.
+                - p_use_label (float | bool): with labels or not.
 
         Returns:
-            AssignResult :
+            :obj:`SamplingResult`: Randomly generated sampling result.
 
         Example:
             >>> from mmdet.core.bbox.samplers.sampling_result import *  # NOQA

mmdet/core/evaluation/mean_ap.py

@@ -279,10 +279,11 @@ def eval_map(det_results,
             per-class detected bboxes.
         annotations (list[dict]): Ground truth annotations where each item of
             the list indicates an image. Keys of annotations are:
-                - "bboxes": numpy array of shape (n, 4)
-                - "labels": numpy array of shape (n, )
-                - "bboxes_ignore" (optional): numpy array of shape (k, 4)
-                - "labels_ignore" (optional): numpy array of shape (k, )
+
+            - `bboxes`: numpy array of shape (n, 4)
+            - `labels`: numpy array of shape (n, )
+            - `bboxes_ignore` (optional): numpy array of shape (k, 4)
+            - `labels_ignore` (optional): numpy array of shape (k, )
         scale_ranges (list[tuple] | None): Range of scales to be evaluated,
             in the format [(min1, max1), (min2, max2), ...]. A range of
             (32, 64) means the area range between (32**2, 64**2).

mmdet/core/fp16/decorators.py

@@ -19,21 +19,21 @@ def auto_fp16(apply_to=None, out_fp32=False):
             `None` indicates all arguments.
         out_fp32 (bool): Whether to convert the output back to fp32.
 
-    :Example:
-
-        class MyModule1(nn.Module)
-
-            # Convert x and y to fp16
-            @auto_fp16()
-            def forward(self, x, y):
-                pass
-
-        class MyModule2(nn.Module):
-
-            # convert pred to fp16
-            @auto_fp16(apply_to=('pred', ))
-            def do_something(self, pred, others):
-                pass
+    Example:
+
+        >>> class MyModule1(nn.Module)
+        >>>
+        >>>     # Convert x and y to fp16
+        >>>     @auto_fp16()
+        >>>     def forward(self, x, y):
+        >>>         pass
+
+        >>> class MyModule2(nn.Module):
+        >>>
+        >>>     # convert pred to fp16
+        >>>     @auto_fp16(apply_to=('pred', ))
+        >>>     def do_something(self, pred, others):
+        >>>         pass
     """
 
     def auto_fp16_wrapper(old_func):
@@ -97,21 +97,21 @@ def force_fp32(apply_to=None, out_fp16=False):
             `None` indicates all arguments.
         out_fp16 (bool): Whether to convert the output back to fp16.
 
-    :Example:
-
-        class MyModule1(nn.Module)
-
-            # Convert x and y to fp32
-            @force_fp32()
-            def loss(self, x, y):
-                pass
-
-        class MyModule2(nn.Module):
-
-            # convert pred to fp32
-            @force_fp32(apply_to=('pred', ))
-            def post_process(self, pred, others):
-                pass
+    Example:
+
+        >>> class MyModule1(nn.Module)
+        >>>
+        >>>     # Convert x and y to fp32
+        >>>     @force_fp32()
+        >>>     def loss(self, x, y):
+        >>>         pass
+
+        >>> class MyModule2(nn.Module):
+        >>>
+        >>>     # convert pred to fp32
+        >>>     @force_fp32(apply_to=('pred', ))
+        >>>     def post_process(self, pred, others):
+        >>>         pass
     """
 
     def force_fp32_wrapper(old_func):

mmdet/core/optimizer/default_constructor.py

@@ -20,9 +20,10 @@ class DefaultOptimizerConstructor(object):
                 - type: class name of the optimizer.
             Optional fields are:
                 - any arguments of the corresponding optimizer type, e.g.,
-                  lr, weight_decay, momentum, etc.
-        paramwise_cfg (dict, optional): Parameter-wise options. Accepted fields
-            are:
+                    lr, weight_decay, momentum, etc.
+        paramwise_cfg (dict, optional): Parameter-wise options.
+            Accepted fields are
+
             - bias_lr_mult (float): It will be multiplied to the learning
                 rate for all bias parameters (except for those in normalization
                 layers).

mmdet/datasets/custom.py

@@ -13,23 +13,25 @@ from .pipelines import Compose
 class CustomDataset(Dataset):
     """Custom dataset for detection.
 
-    Annotation format:
-    [
-        {
-            'filename': 'a.jpg',
-            'width': 1280,
-            'height': 720,
-            'ann': {
-                'bboxes': <np.ndarray> (n, 4),
-                'labels': <np.ndarray> (n, ),
-                'bboxes_ignore': <np.ndarray> (k, 4), (optional field)
-                'labels_ignore': <np.ndarray> (k, 4) (optional field)
-            }
-        },
-        ...
-    ]
-
-    The `ann` field is optional for testing.
+    The annotation format is shown as follows. The `ann` field is optional for
+    testing.
+
+    .. code-block::
+
+        [
+            {
+                'filename': 'a.jpg',
+                'width': 1280,
+                'height': 720,
+                'ann': {
+                    'bboxes': <np.ndarray> (n, 4),
+                    'labels': <np.ndarray> (n, ),
+                    'bboxes_ignore': <np.ndarray> (k, 4), (optional field)
+                    'labels_ignore': <np.ndarray> (k, 4) (optional field)
+                }
+            },
+            ...
+        ]
     """
 
     CLASSES = None

mmdet/datasets/samplers/group_sampler.py

@@ -50,12 +50,15 @@ class GroupSampler(Sampler):
 
 class DistributedGroupSampler(Sampler):
     """Sampler that restricts data loading to a subset of the dataset.
+
     It is especially useful in conjunction with
     :class:`torch.nn.parallel.DistributedDataParallel`. In such case, each
     process can pass a DistributedSampler instance as a DataLoader sampler,
     and load a subset of the original dataset that is exclusive to it.
+
     .. note::
         Dataset is assumed to be of constant size.
+
     Arguments:
         dataset: Dataset used for sampling.
         num_replicas (optional): Number of processes participating in

mmdet/models/anchor_heads/guided_anchor_head.py

@@ -59,10 +59,11 @@ class GuidedAnchorHead(AnchorHead):
     This GuidedAnchorHead will predict high-quality feature guided
     anchors and locations where anchors will be kept in inference.
     There are mainly 3 categories of bounding-boxes.
-    - Sampled (9) pairs for target assignment. (approxes)
-    - The square boxes where the predicted anchors are based on.
-        (squares)
+
+    - Sampled 9 pairs for target assignment. (approxes)
+    - The square boxes where the predicted anchors are based on. (squares)
     - Guided anchors.
+
     Please refer to https://arxiv.org/abs/1901.03278 for more details.
 
     Args:

mmdet/models/anchor_heads/reppoints_head.py

@@ -183,8 +183,8 @@ class RepPointsHead(nn.Module):
         normal_init(self.reppoints_pts_refine_out, std=0.01)
 
     def points2bbox(self, pts, y_first=True):
-        """
-        Converting the points set into bounding box.
+        """Converting the points set into bounding box.
+
         :param pts: the input points sets (fields), each points
             set (fields) is represented as 2n scalar.
         :param y_first: if y_fisrt=True, the point set is represented as
@@ -234,9 +234,9 @@ class RepPointsHead(nn.Module):
         return bbox
 
     def gen_grid_from_reg(self, reg, previous_boxes):
-        """
-        Base on the previous bboxes and regression values, we compute the
-            regressed bboxes and generate the grids on the bboxes.
+        """Base on the previous bboxes and regression values, we compute the
+        regressed bboxes and generate the grids on the bboxes.
+
         :param reg: the regression value to previous bboxes.
         :param previous_boxes: previous bboxes.
         :return: generate grids on the regressed bboxes.
@@ -470,7 +470,7 @@ class RepPointsHead(nn.Module):
                     label_channels=1,
                     unmap_outputs=True):
         """Compute corresponding GT box and classification targets for
-            proposals.
+        proposals.
 
         Args:
             proposals_list (list[list]): Multi level points/bboxes of each
@@ -489,16 +489,14 @@ class RepPointsHead(nn.Module):
                 set of anchors.
 
         Returns:
-            tuple
-                labels_list (list[Tensor]): Labels of each level
-                label_weights_list (list[Tensor]): Label weights of each level
-                bbox_gt_list (list[Tensor]): Ground truth bbox of each level
-                proposal_list (list[Tensor]): Proposals(points/bboxes) of each
-                    level
-                proposal_weights_list (list[Tensor]): Proposal weights of each
-                    level
-                num_total_pos (int): Number of positive samples in all images
-                num_total_neg (int): Number of negative samples in all images
+            tuple:
+                - labels_list (list[Tensor]): Labels of each level.
+                - label_weights_list (list[Tensor]): Label weights of each level.  # noqa: E501
+                - bbox_gt_list (list[Tensor]): Ground truth bbox of each level.
+                - proposal_list (list[Tensor]): Proposals(points/bboxes) of each level.  # noqa: E501
+                - proposal_weights_list (list[Tensor]): Proposal weights of each level.  # noqa: E501
+                - num_total_pos (int): Number of positive samples in all images.  # noqa: E501
+                - num_total_neg (int): Number of negative samples in all images.  # noqa: E501
         """
         assert stage in ['init', 'refine']
         num_imgs = len(img_metas)

requirements/readthedocs.txt

+torch
+torchvision