[Docs] Refactor the api structures of docs (#2254)

* [Docs] Refactor the api structures of docs

* refine api structures of docs

* Update zh_cn

* update branch

docs/zh_cn/api/image.rst

+.. role:: hidden
+    :class: hidden-section
+
+mmcv.image
+===================================
+
+.. contents:: mmcv.image
+   :depth: 2
+   :local:
+   :backlinks: top
+
+.. currentmodule:: mmcv.image
+
+IO
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   imfrombytes
+   imread
+   imwrite
+   use_backend
+
+Color Space
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   bgr2gray
+   bgr2hls
+   bgr2hsv
+   bgr2rgb
+   bgr2ycbcr
+   gray2bgr
+   gray2rgb
+   hls2bgr
+   hsv2bgr
+   imconvert
+   rgb2bgr
+   rgb2gray
+   rgb2ycbcr
+   ycbcr2bgr
+   ycbcr2rgb
+
+Geometric
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   cutout
+   imcrop
+   imflip
+   impad
+   impad_to_multiple
+   imrescale
+   imresize
+   imresize_like
+   imresize_to_multiple
+   imrotate
+   imshear
+   imtranslate
+   rescale_size
+
+Photometric
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   adjust_brightness
+   adjust_color
+   adjust_contrast
+   adjust_hue
+   adjust_lighting
+   adjust_sharpness
+   auto_contrast
+   clahe
+   imdenormalize
+   imequalize
+   iminvert
+   imnormalize
+   lut_transform
+   posterize
+   solarize
+
+Miscellaneous
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   tensor2imgs

docs/zh_cn/api/ops.rst

+.. role:: hidden
+    :class: hidden-section
+
+mmcv.ops
+===================================
+
+.. contents:: mmcv.ops
+   :depth: 2
+   :local:
+   :backlinks: top
+
+.. currentmodule:: mmcv.ops
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: classtemplate.rst
+
+   BorderAlign
+   CARAFE
+   CARAFENaive
+   CARAFEPack
+   Conv2d
+   ConvTranspose2d
+   CornerPool
+   Correlation
+   CrissCrossAttention
+   DeformConv2d
+   DeformConv2dPack
+   DeformRoIPool
+   DeformRoIPoolPack
+   DynamicScatter
+   FusedBiasLeakyReLU
+   GroupAll
+   Linear
+   MaskedConv2d
+   MaxPool2d
+   ModulatedDeformConv2d
+   ModulatedDeformConv2dPack
+   ModulatedDeformRoIPoolPack
+   MultiScaleDeformableAttention
+   PSAMask
+   PointsSampler
+   PrRoIPool
+   QueryAndGroup
+   RiRoIAlignRotated
+   RoIAlign
+   RoIAlignRotated
+   RoIAwarePool3d
+   RoIPointPool3d
+   RoIPool
+   SAConv2d
+   SigmoidFocalLoss
+   SimpleRoIAlign
+   SoftmaxFocalLoss
+   SparseConv2d
+   SparseConv3d
+   SparseConvTensor
+   SparseConvTranspose2d
+   SparseConvTranspose3d
+   SparseInverseConv2d
+   SparseInverseConv3d
+   SparseMaxPool2d
+   SparseMaxPool3d
+   SparseModule
+   SparseSequential
+   SubMConv2d
+   SubMConv3d
+   SyncBatchNorm
+   TINShift
+   Voxelization
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   active_rotated_filter
+   assign_score_withk
+   ball_query
+   batched_nms
+   bbox_overlaps
+   border_align
+   box_iou_rotated
+   boxes_iou3d
+   boxes_iou_bev
+   boxes_overlap_bev
+   carafe
+   carafe_naive
+   chamfer_distance
+   contour_expand
+   convex_giou
+   convex_iou
+   deform_conv2d
+   deform_roi_pool
+   diff_iou_rotated_2d
+   diff_iou_rotated_3d
+   dynamic_scatter
+   furthest_point_sample
+   furthest_point_sample_with_dist
+   fused_bias_leakyrelu
+   gather_points
+   grouping_operation
+   knn
+   masked_conv2d
+   min_area_polygons
+   modulated_deform_conv2d
+   nms
+   nms3d
+   nms3d_normal
+   nms_bev
+   nms_match
+   nms_normal_bev
+   nms_rotated
+   pixel_group
+   point_sample
+   points_in_boxes_all
+   points_in_boxes_cpu
+   points_in_boxes_part
+   points_in_polygons
+   prroi_pool
+   rel_roi_point_to_rel_img_point
+   riroi_align_rotated
+   roi_align
+   roi_align_rotated
+   roi_pool
+   rotated_feature_align
+   scatter_nd
+   sigmoid_focal_loss
+   soft_nms
+   softmax_focal_loss
+   three_interpolate
+   three_nn
+   tin_shift
+   upfirdn2d
+   voxelization

docs/zh_cn/api/transforms.rst

+.. role:: hidden
+    :class: hidden-section
+
+mmcv.transforms
+===================================
+
+.. currentmodule:: mmcv.transforms
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: classtemplate.rst
+
+   BaseTransform
+
+Loading
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: classtemplate.rst
+
+   LoadAnnotations
+   LoadImageFromFile
+
+Processing
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: classtemplate.rst
+
+   CenterCrop
+   MultiScaleFlipAug
+   Normalize
+   Pad
+   RandomChoiceResize
+   RandomFlip
+   RandomGrayscale
+   RandomResize
+   Resize
+
+Wrapper
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: classtemplate.rst
+
+   Compose
+   KeyMapper
+   RandomApply
+   RandomChoice
+   TransformBroadcaster

docs/zh_cn/api/utils.rst

+.. role:: hidden
+    :class: hidden-section
+
+mmcv.utils
+===================================
+
+.. contents:: mmcv.utils
+   :depth: 2
+   :local:
+   :backlinks: top
+
+.. currentmodule:: mmcv.utils
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   IS_CUDA_AVAILABLE
+   IS_MLU_AVAILABLE
+   IS_MPS_AVAILABLE
+   collect_env
+   jit
+   skip_no_elena

docs/zh_cn/api/video.rst

+.. role:: hidden
+    :class: hidden-section
+
+mmcv.video
+===================================
+
+.. contents:: mmcv.video
+   :depth: 2
+   :local:
+   :backlinks: top
+
+.. currentmodule:: mmcv.video
+
+IO
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: classtemplate.rst
+
+   VideoReader
+   Cache
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   frames2video
+
+Optical Flow
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   dequantize_flow
+   flow_from_bytes
+   flow_warp
+   flowread
+   flowwrite
+   quantize_flow
+   sparse_flow_from_bytes
+
+Video Processing
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   concat_video
+   convert_video
+   cut_video
+   resize_video

docs/zh_cn/api/visualization.rst

+.. role:: hidden
+    :class: hidden-section
+
+mmcv.visualization
+===================================
+
+.. contents:: mmcv.visualization
+   :depth: 2
+   :local:
+   :backlinks: top
+
+.. currentmodule:: mmcv.visualization
+
+Color
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: classtemplate.rst
+
+   Color
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   color_val
+
+Image
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   imshow
+   imshow_bboxes
+   imshow_det_bboxes
+
+Optical Flow
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   flow2rgb
+   flowshow
+   make_color_wheel

docs/zh_cn/conf.py

@@ -47,6 +47,8 @@ release = __version__
 
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinx.ext.autosectionlabel',
@@ -57,6 +59,14 @@ extensions = [
 
 myst_heading_anchors = 4
 
+# Configuration for intersphinx
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable', None),
+    'torch': ('https://pytorch.org/docs/stable/', None),
+    'mmengine': ('https://mmengine.readthedocs.io/en/latest', None),
+}
+
 autodoc_mock_imports = ['mmcv._ext', 'mmcv.utils.ext_loader', 'torchvision']
 autosectionlabel_prefix_document = True
 

docs/zh_cn/docutils.conf

+[html writers]
+table_style: colwidths-auto

docs/zh_cn/index.rst

@@ -33,8 +33,6 @@
    compatibility.md
 
 .. toctree::
-   :maxdepth: 2
-   :caption: 常见问题
 
    faq.md
 
@@ -46,10 +44,17 @@
    community/pr.md
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: API 文档
 
-   api.rst
+   mmcv.image <api/image>
+   mmcv.video <api/video>
+   mmcv.visualization <api/visualization>
+   mmcv.cnn <api/cnn>
+   mmcv.ops <api/ops>
+   mmcv.transforms <api/transforms>
+   mmcv.arraymisc <api/arraymisc>
+   mmcv.utils <api/utils>
 
 
 Indices and tables

mmcv/image/geometric.py

@@ -494,6 +494,7 @@ def impad(img,
             areas when padding_mode is 'constant'. Default: 0.
         padding_mode (str): Type of padding. Should be: constant, edge,
             reflect or symmetric. Default: constant.
+
             - constant: pads with a constant value, this value is specified
               with pad_val.
             - edge: pads with the last value at the edge of the image.

mmcv/ops/iou3d.py

@@ -163,10 +163,10 @@ def nms_bev(boxes: Tensor,
             post_max_size: Optional[int] = None) -> Tensor:
     """NMS function GPU implementation (for BEV boxes).
 
-    The overlap of two
-    boxes for IoU calculation is defined as the exact overlapping area of the
-    two boxes. In this function, one can also set ``pre_max_size`` and
-    ``post_max_size``.
+    The overlap of two boxes for IoU calculation is defined as the exact
+    overlapping area of the two boxes. In this function, one can also
+    set ``pre_max_size`` and ``post_max_size``.
+
     Args:
         boxes (torch.Tensor): Input boxes with the shape of (N, 5)
             ([x1, y1, x2, y2, ry]).
@@ -176,6 +176,7 @@ def nms_bev(boxes: Tensor,
             Default: None.
         post_max_size (int, optional): Max size of boxes after NMS.
             Default: None.
+
     Returns:
         torch.Tensor: Indexes after NMS.
     """
@@ -203,14 +204,15 @@ def nms_bev(boxes: Tensor,
 def nms_normal_bev(boxes: Tensor, scores: Tensor, thresh: float) -> Tensor:
     """Normal NMS function GPU implementation (for BEV boxes).
 
-    The overlap of
-    two boxes for IoU calculation is defined as the exact overlapping area of
-    the two boxes WITH their yaw angle set to 0.
+    The overlap of two boxes for IoU calculation is defined as the exact
+    overlapping area of the two boxes WITH their yaw angle set to 0.
+
     Args:
         boxes (torch.Tensor): Input boxes with shape (N, 5)
             ([x1, y1, x2, y2, ry]).
         scores (torch.Tensor): Scores of predicted boxes with shape (N,).
         thresh (float): Overlap threshold of NMS.
+
     Returns:
         torch.Tensor: Remaining indices with scores in descending order.
     """

mmcv/transforms/base.py

@@ -4,6 +4,7 @@ from typing import Dict, List, Optional, Tuple, Union
 
 
 class BaseTransform(metaclass=ABCMeta):
+    """Base class for all transformations."""
 
     def __call__(self,
                  results: Dict) -> Optional[Union[Dict, Tuple[List, List]]]:

mmcv/transforms/loading.py

@@ -27,11 +27,11 @@ class LoadImageFromFile(BaseTransform):
         to_float32 (bool): Whether to convert the loaded image to a float32
             numpy array. If set to False, the loaded image is an uint8 array.
             Defaults to False.
-        color_type (str): The flag argument for :func:``mmcv.imfrombytes``.
+        color_type (str): The flag argument for :func:`mmcv.imfrombytes`.
             Defaults to 'color'.
         imdecode_backend (str): The image decoding backend type. The backend
-            argument for :func:``mmcv.imfrombytes``.
-            See :func:``mmcv.imfrombytes`` for details.
+            argument for :func:`mmcv.imfrombytes`.
+            See :func:`mmcv.imfrombytes` for details.
             Defaults to 'cv2'.
         file_client_args (dict): Arguments to instantiate a FileClient.
             See :class:`mmengine.fileio.FileClient` for details.
@@ -57,7 +57,8 @@ class LoadImageFromFile(BaseTransform):
         """Functions to load image.
 
         Args:
-            results (dict): Result dict from :obj:``mmcv.BaseDataset``.
+            results (dict): Result dict from
+                :class:`mmengine.dataset.BaseDataset`.
 
         Returns:
             dict: The dict contains loaded image and meta information.
@@ -165,11 +166,11 @@ class LoadAnnotations(BaseTransform):
         with_keypoints (bool): Whether to parse and load the keypoints
             annotation. Defaults to False.
         imdecode_backend (str): The image decoding backend type. The backend
-            argument for :func:``mmcv.imfrombytes``.
-            See :fun:``mmcv.imfrombytes`` for details.
+            argument for :func:`mmcv.imfrombytes`.
+            See :func:`mmcv.imfrombytes` for details.
             Defaults to 'cv2'.
         file_client_args (dict): Arguments to instantiate a FileClient.
-            See :class:``mmengine.fileio.FileClient`` for details.
+            See :class:`mmengine.fileio.FileClient` for details.
             Defaults to ``dict(backend='disk')``.
     """
 
@@ -195,7 +196,9 @@ class LoadAnnotations(BaseTransform):
         """Private function to load bounding box annotations.
 
         Args:
-            results (dict): Result dict from :obj:``mmcv.BaseDataset``.
+            results (dict): Result dict from
+                :class:`mmengine.dataset.BaseDataset`.
+
         Returns:
             dict: The dict contains loaded bounding box annotations.
         """
@@ -209,7 +212,8 @@ class LoadAnnotations(BaseTransform):
         """Private function to load label annotations.
 
         Args:
-            results (dict): Result dict from :obj :obj:``mmcv.BaseDataset``.
+            results (dict): Result dict from
+                :class:`mmengine.dataset.BaseDataset`.
 
         Returns:
             dict: The dict contains loaded label annotations.
@@ -224,7 +228,8 @@ class LoadAnnotations(BaseTransform):
         """Private function to load semantic segmentation annotations.
 
         Args:
-            results (dict): Result dict from :obj:``mmcv.BaseDataset``.
+            results (dict): Result dict from
+                :class:`mmengine.dataset.BaseDataset`.
 
         Returns:
             dict: The dict contains loaded semantic segmentation annotations.
@@ -239,7 +244,9 @@ class LoadAnnotations(BaseTransform):
         """Private function to load keypoints annotations.
 
         Args:
-            results (dict): Result dict from :obj:``mmcv.BaseDataset``.
+            results (dict): Result dict from
+                :class:`mmengine.dataset.BaseDataset`.
+
         Returns:
             dict: The dict contains loaded keypoints annotations.
         """
@@ -253,7 +260,8 @@ class LoadAnnotations(BaseTransform):
         """Function to load multiple types annotations.
 
         Args:
-            results (dict): Result dict from :obj:``mmcv.BaseDataset``.
+            results (dict): Result dict from
+                :class:`mmengine.dataset.BaseDataset`.
 
         Returns:
             dict: The dict contains loaded bounding box, label and

mmcv/transforms/processing.py

@@ -301,14 +301,15 @@ class Pad(BaseTransform):
             None.
         pad_to_square (bool): Whether to pad the image into a square.
             Currently only used for YOLOX. Defaults to False.
-        pad_val (Number | dict[str, Number], optional) - Padding value for if
-            the pad_mode is "constant".  If it is a single number, the value
+        pad_val (Number | dict[str, Number], optional): Padding value for if
+            the pad_mode is "constant". If it is a single number, the value
             to pad the image is the number and to pad the semantic
             segmentation map is 255. If it is a dict, it should have the
             following keys:
 
             - img: The value to pad the image.
             - seg: The value to pad the semantic segmentation map.
+
             Defaults to dict(img=0, seg=255).
         padding_mode (str): Type of padding. Should be: constant, edge,
             reflect or symmetric. Defaults to 'constant'.
@@ -987,38 +988,44 @@ class RandomFlip(BaseTransform):
     keys: flip, flip_direction, img, gt_bboxes, gt_seg_map, and
     gt_keypoints. There are 3 flip modes:
 
-     - ``prob`` is float, ``direction`` is string: the image will be
-         ``direction``ly flipped with probability of ``prob`` .
-         E.g., ``prob=0.5``, ``direction='horizontal'``,
-         then image will be horizontally flipped with probability of 0.5.
-     - ``prob`` is float, ``direction`` is list of string: the image will
-         be ``direction[i]``ly flipped with probability of
-         ``prob/len(direction)``.
-         E.g., ``prob=0.5``, ``direction=['horizontal', 'vertical']``,
-         then image will be horizontally flipped with probability of 0.25,
-         vertically with probability of 0.25.
-     - ``prob`` is list of float, ``direction`` is list of string:
-         given ``len(prob) == len(direction)``, the image will
-         be ``direction[i]``ly flipped with probability of ``prob[i]``.
-         E.g., ``prob=[0.3, 0.5]``, ``direction=['horizontal',
-         'vertical']``, then image will be horizontally flipped with
-         probability of 0.3, vertically with probability of 0.5.
+    - ``prob`` is float, ``direction`` is string: the image will be
+      ``direction``ly flipped with probability of ``prob`` .
+      E.g., ``prob=0.5``, ``direction='horizontal'``,
+      then image will be horizontally flipped with probability of 0.5.
+
+    - ``prob`` is float, ``direction`` is list of string: the image will
+      be ``direction[i]``ly flipped with probability of
+      ``prob/len(direction)``.
+      E.g., ``prob=0.5``, ``direction=['horizontal', 'vertical']``,
+      then image will be horizontally flipped with probability of 0.25,
+      vertically with probability of 0.25.
+
+    - ``prob`` is list of float, ``direction`` is list of string:
+      given ``len(prob) == len(direction)``, the image will
+      be ``direction[i]``ly flipped with probability of ``prob[i]``.
+      E.g., ``prob=[0.3, 0.5]``, ``direction=['horizontal',
+      'vertical']``, then image will be horizontally flipped with
+      probability of 0.3, vertically with probability of 0.5.
 
     Required Keys:
-        - img
-        - gt_bboxes (optional)
-        - gt_seg_map (optional)
-        - gt_keypoints (optional)
+
+    - img
+    - gt_bboxes (optional)
+    - gt_seg_map (optional)
+    - gt_keypoints (optional)
 
     Modified Keys:
-        - img
-        - gt_bboxes (optional)
-        - gt_seg_map (optional)
-        - gt_keypoints (optional)
+
+    - img
+    - gt_bboxes (optional)
+    - gt_seg_map (optional)
+    - gt_keypoints (optional)
 
     Added Keys:
-        - flip
-        - flip_direction
+
+    - flip
+    - flip_direction
+
     Args:
          prob (float | list[float], optional): The flipping probability.
              Defaults to None.
@@ -1234,11 +1241,11 @@ class RandomResize(BaseTransform):
     is for width, and ``ratio_range[1]`` is for height.
 
     - if ``keep_ratio`` is True, the minimum value of ``target_scale`` will be
-    used to set the shorter side and the maximum value will be used to
-    set the longer side.
+      used to set the shorter side and the maximum value will be used to
+      set the longer side.
 
     - if ``keep_ratio`` is False, the value of ``target_scale`` will be used to
-    reisze the width and height accordingly.
+      reisze the width and height accordingly.
 
     Required Keys: