[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] Refactor the api structures of docs (#2254)
* [Docs] Refactor the api structures of docs * refine api structures of docs * Update zh_cn * update branch
264e170c · Zaida Zhou · GitHub · c57b8b18 · 264e170c · 264e170c
Unverified Commit 264e170c authored Sep 25, 2022 by Zaida Zhou Committed by GitHub Sep 25, 2022
20 changed files
--- a/.gitignore
+++ b/.gitignore
@@ -68,7 +68,9 @@ instance/

 # Sphinx documentation
 docs/en/_build/
+docs/en/api/generated/
 docs/zh_cn/_build/
+docs/zh_cn/api/generated/

 # PyBuilder
 target/

--- a/docs/en/_static/css/readthedocs.css
+++ b/docs/en/_static/css/readthedocs.css
@@ -4,3 +4,7 @@
    height: 40px;
    width: 85px;
 }
+
+table.colwidths-auto td {
+    width: 50%
+}
--- a/docs/en/_templates/classtemplate.rst
+++ b/docs/en/_templates/classtemplate.rst
+.. role:: hidden
+    :class: hidden-section
+.. currentmodule:: {{ module }}
+
+
+{{ name | underline}}
+
+.. autoclass:: {{ name }}
+    :members:
+
+
+..
+  autogenerated from source/_templates/classtemplate.rst
+  note it does not have :inherited-members:
--- a/docs/en/api.rst
+++ b/docs/en/api.rst
-image
------
-.. automodule:: mmcv.image
-    :members:
-
-video
------
-.. automodule:: mmcv.video
-    :members:
-
-arraymisc
---------
-.. automodule:: mmcv.arraymisc
-    :members:
-
-visualization
--------------
-.. automodule:: mmcv.visualization
-    :members:
-
-utils
-----
-.. automodule:: mmcv.utils
-    :members:
-
-cnn
----
-.. automodule:: mmcv.cnn
-    :members:
-
-ops
------
-.. automodule:: mmcv.ops
-    :members:
-
-transforms
---------
-.. automodule:: mmcv.transforms
-    :members:
--- a/docs/en/api/arraymisc.rst
+++ b/docs/en/api/arraymisc.rst
+.. role:: hidden
+    :class: hidden-section
+
+mmcv.arraymisc
+===================================
+
+.. contents:: mmcv.arraymisc
+   :depth: 2
+   :local:
+   :backlinks: top
+
+.. currentmodule:: mmcv.arraymisc
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   quantize
+   dequantize
--- a/docs/en/api/cnn.rst
+++ b/docs/en/api/cnn.rst
+.. role:: hidden
+    :class: hidden-section
+
+mmcv.cnn
+===================================
+
+.. contents:: mmcv.cnn
+   :depth: 2
+   :local:
+   :backlinks: top
+
+.. currentmodule:: mmcv.cnn
+
+Module
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: classtemplate.rst
+
+   ContextBlock
+   Conv2d
+   Conv3d
+   ConvAWS2d
+   ConvModule
+   ConvTranspose2d
+   ConvTranspose3d
+   ConvWS2d
+   DepthwiseSeparableConvModule
+   GeneralizedAttention
+   HSigmoid
+   HSwish
+   Linear
+   MaxPool2d
+   MaxPool3d
+   NonLocal1d
+   NonLocal2d
+   NonLocal3d
+   Scale
+   Swish
+
+Build Function
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   build_activation_layer
+   build_conv_layer
+   build_norm_layer
+   build_padding_layer
+   build_plugin_layer
+   build_upsample_layer
+
+Miscellaneous
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   fuse_conv_bn
+   conv_ws_2d
+   is_norm
+   make_res_layer
+   make_vgg_layer
+   get_model_complexity_info
--- a/docs/en/api/image.rst
+++ b/docs/en/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
--- a/docs/en/api/ops.rst
+++ b/docs/en/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
--- a/docs/en/api/transforms.rst
+++ b/docs/en/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
--- a/docs/en/api/utils.rst
+++ b/docs/en/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
--- a/docs/en/api/video.rst
+++ b/docs/en/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
--- a/docs/en/api/visualization.rst
+++ b/docs/en/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
--- a/docs/en/conf.py
+++ b/docs/en/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_markdown_tables',
@@ -56,6 +58,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']

 # Add any paths that contain templates here, relative to this directory.

--- a/docs/en/docutils.conf
+++ b/docs/en/docutils.conf
+[html writers]
+table_style: colwidths-auto
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -38,8 +38,6 @@ You can switch between Chinese and English documents in the lower-left corner of
   compatibility.md

 .. toctree::
-   :maxdepth: 2
-   :caption: FAQ

   faq.md

@@ -51,10 +49,17 @@ You can switch between Chinese and English documents in the lower-left corner of
   community/pr.md

 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
   :caption: API Reference

-   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
 ==================

--- a/docs/zh_cn/_static/css/readthedocs.css
+++ b/docs/zh_cn/_static/css/readthedocs.css
@@ -4,3 +4,7 @@
    height: 40px;
    width: 85px;
 }
+
+table.colwidths-auto td {
+    width: 50%
+}
--- a/docs/zh_cn/_templates/classtemplate.rst
+++ b/docs/zh_cn/_templates/classtemplate.rst
+.. role:: hidden
+    :class: hidden-section
+.. currentmodule:: {{ module }}
+
+
+{{ name | underline}}
+
+.. autoclass:: {{ name }}
+    :members:
+
+
+..
+  autogenerated from source/_templates/classtemplate.rst
+  note it does not have :inherited-members:
--- a/docs/zh_cn/api.rst
+++ b/docs/zh_cn/api.rst
-image
------
-.. automodule:: mmcv.image
-    :members:
-
-video
------
-.. automodule:: mmcv.video
-    :members:
-
-arraymisc
---------
-.. automodule:: mmcv.arraymisc
-    :members:
-
-visualization
--------------
-.. automodule:: mmcv.visualization
-    :members:
-
-utils
-----
-.. automodule:: mmcv.utils
-    :members:
-
-cnn
----
-.. automodule:: mmcv.cnn
-    :members:
-
-ops
------
-.. automodule:: mmcv.ops
-    :members:
-
-transform
---------
-.. automodule:: mmcv.transform
-    :members:
--- a/docs/zh_cn/api/arraymisc.rst
+++ b/docs/zh_cn/api/arraymisc.rst
+.. role:: hidden
+    :class: hidden-section
+
+mmcv.arraymisc
+===================================
+
+.. contents:: mmcv.arraymisc
+   :depth: 2
+   :local:
+   :backlinks: top
+
+.. currentmodule:: mmcv.arraymisc
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   quantize
+   dequantize
--- a/docs/zh_cn/api/cnn.rst
+++ b/docs/zh_cn/api/cnn.rst
+.. role:: hidden
+    :class: hidden-section
+
+mmcv.cnn
+===================================
+
+.. contents:: mmcv.cnn
+   :depth: 2
+   :local:
+   :backlinks: top
+
+.. currentmodule:: mmcv.cnn
+
+Module
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: classtemplate.rst
+
+   ContextBlock
+   Conv2d
+   Conv3d
+   ConvAWS2d
+   ConvModule
+   ConvTranspose2d
+   ConvTranspose3d
+   ConvWS2d
+   DepthwiseSeparableConvModule
+   GeneralizedAttention
+   HSigmoid
+   HSwish
+   Linear
+   MaxPool2d
+   MaxPool3d
+   NonLocal1d
+   NonLocal2d
+   NonLocal3d
+   Scale
+   Swish
+
+Build Function
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   build_activation_layer
+   build_conv_layer
+   build_norm_layer
+   build_padding_layer
+   build_plugin_layer
+   build_upsample_layer
+
+Miscellaneous
+----------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   fuse_conv_bn
+   conv_ws_2d
+   is_norm
+   make_res_layer
+   make_vgg_layer
+   get_model_complexity_info