[Docs] Refactor docs (#1102)

* [Docs] Refactor documentation

* [Docs] Refactor documentation

* refactor docs

* refactor docs

* set sphinx==3.1.2

* fix typo

* modify according to comment

* modify according to comment

* modify according to comment

* [Docs] delete unnecessary file

* fix title

* rename

* rename

CONTRIBUTING.md

-# Contributing to OpenMMLab
+## Contributing to OpenMMLab
 
 All kinds of contributions are welcome, including but not limited to the following.
 
 - Fixes (typo, bugs)
 - New features and components
 
-## Workflow
+### Workflow
 
 1. fork and pull the latest OpenMMLab repository
 2. checkout a new branch (do not use master branch for PRs)
@@ -14,9 +14,9 @@ All kinds of contributions are welcome, including but not limited to the followi
 
 Note: If you plan to add some new features that involve large changes, it is encouraged to open an issue for discussion first.
 
-## Code style
+### Code style
 
-### Python
+#### Python
 
 We adopt [PEP8](https://www.python.org/dev/peps/pep-0008/) as the preferred code style.
 
@@ -64,6 +64,6 @@ After this on every commit check code linters and formatter will be enforced.
 
 >Before you create a PR, make sure that your code lints and is formatted by yapf.
 
-### C++ and CUDA
+#### C++ and CUDA
 
 We follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).

docs/api.rst

-API Documentation
+API Reference
 =================
 
 

docs/community.rst

+Community
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+   community/contributing.md

docs/community/contributing.md

+../../CONTRIBUTING.md
\ No newline at end of file

docs/deployment.rst

 Deployment
-========
+================
 
 .. toctree::
     :maxdepth: 2
 
-    onnx.md
-    onnxruntime_op.md
-    onnxruntime_custom_ops.md
-    tensorrt_plugin.md
-    tensorrt_custom_ops.md
+    deployment/onnx.md
+    deployment/onnxruntime_op.md
+    deployment/onnxruntime_custom_ops.md
+    deployment/tensorrt_plugin.md
+    deployment/tensorrt_custom_ops.md

docs/onnx.md → docs/deployment/onnx.md

-# Introduction of `onnx` module in MMCV (Experimental)
+# Introduction of onnx module in MMCV (Experimental)
 
 ## register_extra_symbolics
 

docs/trouble_shooting.md → docs/faq.md

-## Trouble Shooting
+## Frequently Asked Questions
 
 We list some common troubles faced by many users and their corresponding solutions here.
 Feel free to enrich the list if you find any frequent issues and have ways to help others to solve them.

docs/get_started.rst

+Get started
+===================
+
+.. toctree::
+    :maxdepth: 2
+
+    get_started/introduction.md
+    get_started/installation.md
+    get_started/build.md

docs/get_started/installation.md

+## Installation
+
+There are two versions of MMCV:
+
+- **mmcv-full**: comprehensive, with full features and various CUDA ops out of box. It takes longer time to build.
+- **mmcv**: lite, without CUDA ops but all other features, similar to mmcv<1.0.0. It is useful when you do not need those CUDA ops.
+
+**Note**: Do not install both versions in the same environment, otherwise you may encounter errors like `ModuleNotFound`. You need to uninstall one before installing the other. `Installing the full verion is highly recommended if CUDA is avaliable`.
+
+a. Install the full version.
+
+Before installing mmcv-full, make sure that PyTorch has been successfully installed following the [official guide](https://pytorch.org/).
+
+We provide pre-built mmcv packages (recommended) with different PyTorch and CUDA versions to simplify the building.
+
+i. Install the latest version.
+
+The rule for installing the latest ``mmcv-full`` is as follows:
+
+```shell
+pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
+```
+
+Please replace ``{cu_version}`` and ``{torch_version}`` in the url to your desired one. For example,
+to install the latest ``mmcv-full`` with ``CUDA 11`` and ``PyTorch 1.7.0``, use the following command:
+
+```shell
+pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html
+```
+
+For more details, please refer the the following tables and delete ``=={mmcv_version}``.
+
+ii. Install a specified version.
+
+The rule for installing a specified ``mmcv-full`` is as follows:
+
+```shell
+pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
+```
+
+First of all, please refer to the Releases and replace ``{mmcv_version}`` a specified one. e.g. ``1.2.2``.
+Then replace ``{cu_version}`` and ``{torch_version}`` in the url to your desired versions. For example,
+to install ``mmcv-full==1.2.2`` with ``CUDA 11`` and ``PyTorch 1.7.0``, use the following command:
+
+```shell
+pip install mmcv-full==1.2.2 -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html
+```
+
+For more details, please refer the the following tables.
+
+<table class="docutils">
+  <tbody>
+    <tr>
+      <th width="80"> CUDA </th>
+      <th valign="bottom" align="left" width="100">torch 1.8</th>
+      <th valign="bottom" align="left" width="100">torch 1.7</th>
+      <th valign="bottom" align="left" width="100">torch 1.6</th>
+      <th valign="bottom" align="left" width="100">torch 1.5</th>
+      <th valign="bottom" align="left" width="100">torch 1.4</th>
+      <th valign="bottom" align="left" width="100">torch 1.3</th>
+    </tr>
+    <tr>
+      <td align="left">11.1</td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html</code></pre> </details> </td>
+      <td align="left"> </td>
+      <td align="left"> </td>
+      <td align="left"> </td>
+      <td align="left"> </td>
+      <td align="left"> </td>
+    </tr>
+    <tr>
+      <td align="left">11.0</td>
+      <td align="left"> </td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html</code></pre> </details> </td>
+      <td align="left"> </td>
+      <td align="left"> </td>
+      <td align="left"> </td>
+      <td align="left"> </td>
+    </tr>
+    <tr>
+      <td align="left">10.2</td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.7.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.6.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.5.0/index.html</code></pre> </details> </td>
+      <td align="left"> </td>
+      <td align="left"> </td>
+    </tr>
+    <tr>
+      <td align="left">10.1</td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.8.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.7.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.6.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.5.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.4.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu101/torch1.3.0/index.html</code></pre> </details> </td>
+    </tr>
+    <tr>
+      <td align="left">9.2</td>
+      <td align="left"> </td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.7.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.6.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.5.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.4.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cu92/torch1.3.0/index.html</code></pre> </details> </td>
+    </tr>
+    <tr>
+      <td align="left">cpu</td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.8.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.7.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.6.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code> pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.5.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.4.0/index.html</code></pre> </details> </td>
+      <td align="left"><details><summary> install </summary><pre><code>pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.3.0/index.html</code></pre> </details> </td>
+    </tr>
+  </tbody>
+</table>
+
+Another way is to compile locally by running
+
+```python
+pip install mmcv-full
+```
+
+Note that the local compiling may take up to 10 mins.
+
+b. Install the lite version.
+
+```python
+pip install mmcv
+```
+
+c. Install full version with custom operators for onnxruntime
+
+- Check [here](docs/onnxruntime_op.md) for detailed instruction.
+
+If you would like to build MMCV from source, please refer to the [guide](build.md).

docs/get_started/introduction.md

+## Introduction
+
+<div align="center">
+    <img src="https://raw.githubusercontent.com/open-mmlab/mmcv/master/docs/mmcv-logo.png" width="300"/>
+</div>
+
+[![PyPI](https://img.shields.io/pypi/v/mmcv)](https://pypi.org/project/mmcv) [![badge](https://github.com/open-mmlab/mmcv/workflows/build/badge.svg)](https://github.com/open-mmlab/mmcv/actions) [![codecov](https://codecov.io/gh/open-mmlab/mmcv/branch/master/graph/badge.svg)](https://codecov.io/gh/open-mmlab/mmcv) [![license](https://img.shields.io/github/license/open-mmlab/mmcv.svg)](https://github.com/open-mmlab/mmcv/blob/master/LICENSE)
+
+MMCV is a foundational library for computer vision research and supports many
+research projects as below:
+
+- [MMClassification](https://github.com/open-mmlab/mmclassification): OpenMMLab image classification toolbox and benchmark.
+- [MMDetection](https://github.com/open-mmlab/mmdetection): OpenMMLab detection toolbox and benchmark.
+- [MMDetection3D](https://github.com/open-mmlab/mmdetection3d): OpenMMLab's next-generation platform for general 3D object detection.
+- [MMSegmentation](https://github.com/open-mmlab/mmsegmentation): OpenMMLab semantic segmentation toolbox and benchmark.
+- [MMAction2](https://github.com/open-mmlab/mmaction2): OpenMMLab's next-generation action understanding toolbox and benchmark.
+- [MMTracking](https://github.com/open-mmlab/mmtracking): OpenMMLab video perception toolbox and benchmark.
+- [MMPose](https://github.com/open-mmlab/mmpose): OpenMMLab pose estimation toolbox and benchmark.
+- [MMEditing](https://github.com/open-mmlab/mmediting): OpenMMLab image and video editing toolbox.
+- [MMOCR](https://github.com/open-mmlab/mmocr): OpenMMLab text detection, recognition and understanding toolbox.
+- [MMGeneration](https://github.com/open-mmlab/mmgeneration): OpenMMLab image and video generative models toolbox.
+
+It provides the following functionalities.
+
+- Universal IO APIs
+- Image/Video processing
+- Image and annotation visualization
+- Useful utilities (progress bar, timer, ...)
+- PyTorch runner with hooking mechanism
+- Various CNN architectures
+- High-quality implementation of common CUDA ops
+
+Note: MMCV requires Python 3.6+.

docs/index.rst

-
-.. mdinclude:: readme.md
-
-Contents
-========
+Welcome to MMCV's documentation!
+================================
 
 .. toctree::
    :maxdepth: 2
 
-   io.md
-   image.md
-   video.md
-   visualization.md
-   utils.md
-   runner.md
-   registry.md
-   cnn.md
-   ops.md
-   build.md
+   get_started.rst
    deployment.rst
-   trouble_shooting.md
+   understand_mmcv.rst
    api.rst
-
+   faq.md
+   community.rst
 
 
 Indices and tables

docs/readme.md

-../README.md

docs/understand_mmcv.rst

+Understand MMCV
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   understand_mmcv/config.md
+   understand_mmcv/registry.md
+   understand_mmcv/runner.md
+   understand_mmcv/io.md
+   understand_mmcv/data_process.md
+   understand_mmcv/visualization.md
+   understand_mmcv/cnn.md
+   understand_mmcv/ops.md
+   understand_mmcv/utils.md

docs/utils.md → docs/understand_mmcv/config.md

-## Utils
-
-### Config
+## Config
 
 `Config` class is used for manipulating config and config files. It supports
 loading configs from multiple file formats including **python**, **json** and **yaml**.
@@ -69,7 +67,7 @@ a = 1
 b = dict(b1=[0, 1, 2], b2=None)
 ```
 
-#### Inherit from base config without overlapped keys
+### Inherit from base config without overlapped keys
 
 `config_b.py`
 
@@ -90,7 +88,7 @@ d = 'string'
 
 New fields in `config_b.py` are combined with old fields in `config_a.py`
 
-#### Inherit from base config with overlapped keys
+### Inherit from base config with overlapped keys
 
 `config_c.py`
 
@@ -110,7 +108,7 @@ c = (1, 2)
 
 `b.b2=None` in `config_a` is replaced with `b.b2=1` in `config_c.py`.
 
-#### Inherit from base config with ignored fields
+### Inherit from base config with ignored fields
 
 `config_d.py`
 
@@ -130,7 +128,7 @@ c = (1, 2)
 
 You may also set `_delete_=True` to ignore some fields in base configs. All old keys `b1, b2, b3` in `b` are replaced with new keys `b2, b3`.
 
-#### Inherit from multiple base configs (the base configs should not contain the same keys)
+### Inherit from multiple base configs (the base configs should not contain the same keys)
 
 `config_e.py`
 
@@ -154,7 +152,7 @@ _base_ = ['./config_a.py', './config_e.py']
 ...      d='string')
 ```
 
-#### Reference variables from base
+### Reference variables from base
 
 You can reference variables defined in base using the following grammar.
 
@@ -179,75 +177,3 @@ item1 = 'a'
 item2 = dict(item3='b')
 item = dict(a='a', b='b')
 ```
-
-### ProgressBar
-
-If you want to apply a method to a list of items and track the progress, `track_progress`
-is a good choice. It will display a progress bar to tell the progress and ETA.
-
-```python
-import mmcv
-
-def func(item):
-    # do something
-    pass
-
-tasks = [item_1, item_2, ..., item_n]
-
-mmcv.track_progress(func, tasks)
-```
-
-The output is like the following.
-![progress](_static/progress.gif)
-
-There is another method `track_parallel_progress`, which wraps multiprocessing and
-progress visualization.
-
-```python
-mmcv.track_parallel_progress(func, tasks, 8)  # 8 workers
-```
-
-![progress](_static/parallel_progress.gif)
-
-If you want to iterate or enumerate a list of items and track the progress, `track_iter_progress`
-is a good choice. It will display a progress bar to tell the progress and ETA.
-
-```python
-import mmcv
-
-tasks = [item_1, item_2, ..., item_n]
-
-for task in mmcv.track_iter_progress(tasks):
-    # do something like print
-    print(task)
-
-for i, task in enumerate(mmcv.track_iter_progress(tasks)):
-    # do something like print
-    print(i)
-    print(task)
-```
-
-### Timer
-
-It is convenient to compute the runtime of a code block with `Timer`.
-
-```python
-import time
-
-with mmcv.Timer():
-    # simulate some code block
-    time.sleep(1)
-```
-
-or try with `since_start()` and `since_last_check()`. This former can
-return the runtime since the timer starts and the latter will return the time
-since the last time checked.
-
-```python
-timer = mmcv.Timer()
-# code block 1 here
-print(timer.since_start())
-# code block 2 here
-print(timer.since_last_check())
-print(timer.since_start())
-```