Add docs for CNN modules (#266)

* add docs for cnn modules

* minor fix

* update format

* minor fix

* bump version to v0.5.1

.gitignore

@@ -108,4 +108,5 @@ venv.bak/
 .vscode/
 
 # custom
+.DS_Store
 mmcv/video/optflow_warp/flow_warp_module.cpp

README.rst

 MMCV
 ====
 
+.. image:: https://img.shields.io/pypi/v/mmcv
+  :target: https://pypi.org/project/mmcv
+
 .. image:: https://travis-ci.com/open-mmlab/mmcv.svg?branch=master
   :target: https://travis-ci.com/open-mmlab/mmcv
 

docs/api.rst

-API
-====
+API Documentation
+=================
 
 
 fileio
---------------
+-------
 .. automodule:: mmcv.fileio
     :members:
 
 image
---------------
+------
 .. automodule:: mmcv.image
     :members:
 
 video
---------------
+------
 .. automodule:: mmcv.video
     :members:
 
 arraymisc
---------------
+---------
 .. automodule:: mmcv.arraymisc
     :members:
 
@@ -28,11 +28,16 @@ visualization
     :members:
 
 utils
---------------
+-----
 .. automodule:: mmcv.utils
     :members:
 
+cnn
+----
+.. automodule:: mmcv.cnn
+    :members:
+
 runner
---------------
+------
 .. automodule:: mmcv.runner
     :members:

docs/cnn.md

 ## CNN
 
-The subpackage `mmcv.cnn` ships with lots of CNN backbones and the number is growing.
-Different from models provided in `torchvision`, these models are designed
-for actual usage in different cases, with highly customizable interfaces.
-
-Taking ResNet as an example, you can specify the following things:
-
-- number of stages
-- stage of output feature maps
-- location of the stride 2 convolutional layer
-- strides and dilation of each stage
-- whether to freeze some first stages
-- whether to fix BN stats
-- whether to fix BN parameters
-- whether to use checkpoint to save memory
+We provide some building bricks for CNNs, includeing layer building, module bundles and weight initialization.
+
+### Layer building
+
+We may need to try different layers of the same type when running experiments,
+but do not want to modify the code from time to time.
+Here we provide some layer building methods to construct layers from a dict,
+which can be written in configs or specified via command line arguments.
+
+#### Usage
+
+A simplest example is
+```python
+cfg = dict(type='Conv3d')
+layer = build_norm_layer(cfg, in_channels=3, out_channels=8, kernel_size=3)
+```
+
+- `build_conv_layer`: Supported types are Conv1d, Conv2d, Conv3d, Conv (alias for Conv2d).
+- `build_norm_layer`: Supported types are BN1d, BN2d, BN3d, BN (alias for BN2d), SyncBN, GN, LN, IN1d, IN2d, IN3d, IN (alias for IN2d).
+- `build_activation_layer`: Supported types are ReLU, LeakyReLU, PReLU, RReLU, ReLU6, ELU, Sigmoid, Tanh.
+- `build_upsample_layer`: Supported types are nearest, bilinear, deconv, pixel_shuffle.
+- `build_padding_layer`: Supported types are zero, reflect, replicate.
+
+#### Extension
+
+We also allow extending the building methods with custom layers and operators.
+
+1. Write and register your own module.
+
+    ```python
+    from mmcv.cnn import UPSAMPLE_LAYERS
+
+    @UPSAMPLE_LAYERS.register_module()
+    class MyUpsample:
+
+        def __init__(self, scale_factor):
+            pass
+
+        def forward(self, x):
+            pass
+    ```
+
+2. Import `MyUpsample` somewhere (e.g., in `__init__.py`) and then use it.
+
+    ```python
+    cfg = dict(type='MyUpsample', scale_factor=2)
+    layer = build_upsample_layer(cfg)
+    ```
+
+### Module bundles
+
+We also provide common module bundles to facilitate the network construction.
+`ConvModule` is a bundle of convolution, normalization and activation layers,
+please refer to the [api](api.html#mmcv.cnn.ConvModule) for details.
+
+```python
+# conv + bn + relu
+conv = ConvModule(3, 8, 2, norm_cfg=dict(type='BN'))
+# conv + gn + relu
+conv = ConvModule(3, 8, 2, norm_cfg=dict(type='GN', num_groups=2))
+# conv + relu
+conv = ConvModule(3, 8, 2)
+# conv
+conv = ConvModule(3, 8, 2, act_cfg=None)
+# conv + leaky relu
+conv = ConvModule(3, 8, 3, padding=1, act_cfg=dict(type='LeakyReLU'))
+# bn + conv + relu
+conv = ConvModule(
+    3, 8, 2, norm_cfg=dict(type='BN'), order=('norm', 'conv', 'act'))
+```
+
+### Weight initialization
+
+We wrap some initialization methods which accept a module as argument.
+
+- `constant_init`
+- `xavier_init`
+- `normal_init`
+- `uniform_init`
+- `kaiming_init`
+- `caffe2_xavier_init`
+- `bias_init_with_prob`
+
+Examples:
+
+```python
+conv1 = nn.Conv2d(3, 3, 1)
+normal_init(conv1, std=0.01, bias=0)
+xavier_init(conv1, distribution='uniform')
+```

docs/conf.py

@@ -49,7 +49,7 @@ extensions = [
 ]
 
 autodoc_mock_imports = [
-    'cv2', 'numpy', 'torch', 'enum', 'pathlib', 'mmcv._ext'
+    'cv2', 'enum', 'pathlib', 'mmcv._ext', 'pytorch', 'torchvision'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

mmcv/utils/config.py

@@ -297,10 +297,11 @@ class Config(object):
         return format_text
 
     def merge_from_dict(self, options):
-        """ Merge list into cfg_dict
+        """Merge list into cfg_dict
 
         Merge the dict parsed by MultipleKVAction into this cfg.
-        Example,
+
+        Examples:
             >>> options = {'model.backbone.depth': 50,
             ...            'model.backbone.with_cp':True}
             >>> cfg = Config(dict(model=dict(backbone=dict(type='ResNet'))))

mmcv/version.py

 # Copyright (c) Open-MMLab. All rights reserved.
-__version__ = '0.5.0'
+__version__ = '0.5.1'