[Docs] Refine README and installation documentations (#1977)

* [Docs] Refine README

* refine table

* minor refinement

* refine

* refine

* add version info

* add version info

* update version info

* refine

* refine

* add module links in docs/en/introduction

* update docs/en

* fix typo

* update docs/en

* add version.json in zh_cn

* minor refinement

* update version.json

* update Dockerfile

* minor fix

* update installation of macOS

* resolve comments

docker/release/Dockerfile

@@ -16,5 +16,8 @@ RUN apt-get update && apt-get install -y libgl1 libglib2.0-0 \
     && rm -rf /var/lib/apt/lists/*
 
 # Install mmcv-full
-ARG MMCV="1.5.1"
-RUN pip install openmim && mim install mmcv-full==${MMCV} && python -c 'import mmcv;print(mmcv.__version__)'
+ARG MMCV=""
+RUN if [ "${MMCV}" = "" ]; then pip install -U openmim && mim install mmcv-full; else pip install -U openmim && mim install mmcv-full==${MMCV}; fi
+
+# Verify the installation
+RUN python -c 'import mmcv;print(mmcv.__version__)'

docs/en/conf.py

@@ -56,6 +56,8 @@ extensions = [
 
 myst_heading_anchors = 4
 
+myst_enable_extensions = ['colon_fence']
+
 autodoc_mock_imports = ['mmcv._ext', 'mmcv.utils.ext_loader', 'torchvision']
 
 # Add any paths that contain templates here, relative to this directory.

docs/en/get_started/build.md

 ## Build MMCV from source
 
-### Build on Linux or macOS
+### Build mmcv-full
 
-After cloning the repo with
+Before installing mmcv-full, make sure that PyTorch has been successfully installed following the [PyTorch official installation guide](https://pytorch.org/get-started/locally/#start-locally). This can be verified using the following command
 
 ```bash
-git clone https://github.com/open-mmlab/mmcv.git
-cd mmcv
+python -c 'import torch;print(torch.__version__)'
 ```
 
-It is recommended to install `ninja` to speed up the compilation
+If version information is output, then PyTorch is installed.
 
-```bash
-pip install -r requirements/optional.txt
+```{note}
+- To compile ONNX Runtime custom operators, please refer to [How to build custom operators for ONNX Runtime](https://mmcv.readthedocs.io/en/latest/deployment/onnxruntime_op.html#how-to-build-custom-operators-for-onnx-runtime)
+- To compile TensorRT customization, please refer to [How to build TensorRT plugins in MMCV](https://mmcv.readthedocs.io/en/latest/deployment/tensorrt_plugin.html#how-to-build-tensorrt-plugins-in-mmcv)
 ```
 
-You can either
+```{note}
+If you would like to use `opencv-python-headless` instead of `opencv-python`,
+e.g., in a minimum container environment or servers without GUI,
+you can first install it before installing MMCV to skip the installation of `opencv-python`.
+```
 
-- install the lite version
+#### Build on Linux
 
-  ```bash
-  pip install -e .
-  ```
+1. Clone the repo
 
-- install the full version
+   ```bash
+   git clone https://github.com/open-mmlab/mmcv.git
+   cd mmcv
+   ```
 
-  ```bash
-  MMCV_WITH_OPS=1 pip install -e .
-  ```
+2. Install `ninja` and `psutil` to speed up the compilation
 
-If you are on macOS, add the following environment variables before the installing command.
+   ```bash
+   pip install -r requirements/optional.txt
+   ```
 
-```bash
-CC=clang CXX=clang++ CFLAGS='-stdlib=libc++'
-```
+3. Check the nvcc version (requires 9.2+. Skip if no GPU available.)
 
-e.g.,
+   ```bash
+   nvcc --version
+   ```
 
-```bash
-CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' MMCV_WITH_OPS=1 pip install -e .
-```
+   If the above command outputs the following message, it means that the nvcc setting is OK, otherwise you need to set CUDA_HOME.
+
+   ```
+   nvcc: NVIDIA (R) Cuda compiler driver
+   Copyright (c) 2005-2020 NVIDIA Corporation
+   Built on Mon_Nov_30_19:08:53_PST_2020
+   Cuda compilation tools, release 11.2, V11.2.67
+   Build cuda_11.2.r11.2/compiler.29373293_0
+   ```
+
+   :::{note}
+   If you want to support ROCm, you can refer to [AMD ROCm](https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html) to install ROCm.
+   :::
+
+4. Check the gcc version (requires 5.4+)
+
+   ```bash
+   gcc --version
+   ```
+
+5. Start building (takes 10+ min)
+
+   ```bash
+   MMCV_WITH_OPS=1 pip install -e . -v
+   ```
+
+6. Validate the installation
+
+   ```bash
+   python .dev_scripts/check_installation.py
+   ```
+
+   If no error is reported by the above command, the installation is successful. If there is an error reported, please check [Frequently Asked Questions](../faq.md) to see if there is already a solution.
+
+   If no solution is found, please feel free to open an [issue](https://github.com/open-mmlab/mmcv/issues).
+
+#### Build on macOS
 
 ```{note}
-If you would like to use `opencv-python-headless` instead of `opencv-python`,
-e.g., in a minimum container environment or servers without GUI,
-you can first install it before installing MMCV to skip the installation of `opencv-python`.
+If you are using a mac with an M1 chip, install the nightly version of PyTorch, otherwise you will encounter the problem in [issues#2218](https://github.com/open-mmlab/mmcv/issues/2218).
 ```
 
-### Build on Windows
+1. Clone the repo
+
+   ```bash
+   git clone https://github.com/open-mmlab/mmcv.git
+   cd mmcv
+   ```
+
+2. Install `ninja` and `psutil` to speed up the compilation
+
+   ```bash
+   pip install -r requirements/optional.txt
+   ```
+
+3. Start building
+
+   ```bash
+   MMCV_WITH_OPS=1 pip install -e .
+   ```
+
+4. Validate the installation
+
+   ```bash
+   python .dev_scripts/check_installation.py
+   ```
+
+   If no error is reported by the above command, the installation is successful. If there is an error reported, please check [Frequently Asked Questions](../faq.md) to see if there is already a solution.
+
+   If no solution is found, please feel free to open an [issue](https://github.com/open-mmlab/mmcv/issues).
+
+#### Build on Windows
 
 Building MMCV on Windows is a bit more complicated than that on Linux.
 The following instructions show how to get this accomplished.
 
-#### Prerequisite
+##### Prerequisite
 
 The following software is required for building MMCV on windows.
 Install them first.
@@ -71,7 +137,7 @@ Install them first.
 You should know how to set up environment variables, especially `Path`, on Windows. The following instruction relies heavily on this skill.
 ```
 
-#### Setup Python Environment
+##### Common steps
 
 1. Launch Anaconda prompt from Windows Start menu
 
@@ -79,62 +145,45 @@ You should know how to set up environment variables, especially `Path`, on Windo
 
 2. Create a new conda environment
 
-   ```shell
-   conda create --name mmcv python=3.7  # 3.6, 3.7, 3.8 should work too as tested
-   conda activate mmcv  # make sure to activate environment before any operation
+   ```powershell
+   (base) PS C:\Users\xxx> conda create --name mmcv python=3.7
+   (base) PS C:\Users\xxx> conda activate mmcv  # make sure to activate environment before any operation
    ```
 
 3. Install PyTorch. Choose a version based on your need.
 
-   ```shell
-   conda install pytorch torchvision cudatoolkit=10.2 -c pytorch
+   ```powershell
+   # CUDA version
+   (mmcv) PS C:\Users\xxx> conda install pytorch torchvision cudatoolkit=10.2 -c pytorch
+   # CPU version
+   (mmcv) PS C:\Users\xxx> conda install install pytorch torchvision cpuonly -c pytorch
    ```
 
-   We only tested PyTorch version >= 1.6.0.
-
-4. Prepare MMCV source code
+4. Clone the repo
 
-   ```shell
-   git clone https://github.com/open-mmlab/mmcv.git
-   cd mmcv
+   ```powershell
+   (mmcv) PS C:\Users\xxx> git clone https://github.com/open-mmlab/mmcv.git
+   (mmcv) PS C:\Users\xxx\mmcv> cd mmcv
    ```
 
-5. Install required Python packages
+5. Install `ninja` and `psutil` to speed up the compilation
 
-   ```shell
-   pip3 install -r requirements/runtime.txt
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> pip install -r requirements/optional.txt
    ```
 
-6. It is recommended to install `ninja` to speed up the compilation
+6. Install required Python packages
 
-   ```bash
-   pip install -r requirements/optional.txt
+   ```shell
+   (mmcv) PS C:\Users\xxx\mmcv> pip install -r requirements/runtime.txt
    ```
 
-#### Build and install MMCV
-
-MMCV can be built in three ways:
-
-1. Lite version (without ops)
-
-   In this way, no custom ops are compiled and mmcv is a pure python package.
-
-2. Full version (CPU ops)
-
-   Module `ops` will be compiled as a pytorch extension, but only x86 code will be compiled. The compiled ops can be executed on CPU only.
-
-3. Full version (CUDA ops)
-
-   Both x86 and CUDA codes of `ops` module will be compiled. The compiled version can be run on both CPU and CUDA-enabled GPU (if implemented).
-
-##### Common steps
-
-1. Set up MSVC compiler
+7. Set up MSVC compiler
 
    Set Environment variable, add `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.27.29110\bin\Hostx86\x64` to `PATH`, so that `cl.exe` will be available in prompt, as shown below.
 
-   ```none
-   (base) PS C:\Users\xxx> cl
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> cl
    Microsoft (R) C/C++ Optimizing  Compiler Version 19.27.29111 for x64
    Copyright (C) Microsoft Corporation.   All rights reserved.
 
@@ -145,124 +194,135 @@ MMCV can be built in three ways:
 
    You may want to change the system language to English because pytorch will parse text output from `cl.exe` to check its version. However only utf-8 is recognized. Navigate to Control Panel -> Region -> Administrative -> Language for Non-Unicode programs and change it to English.
 
-##### Option 1: Build MMCV (lite version)
+##### Build and install MMCV
 
-After finishing above common steps, launch Anaconda shell from Start menu and issue the following commands:
+mmcv-full can be built in two ways:
 
-```shell
-# activate environment
-conda activate mmcv
-# change directory
-cd mmcv
-# install
-python setup.py develop
-# check
-pip list
-```
+1. Full version (CPU ops)
 
-##### Option 2: Build MMCV (full version with CPU)
+   Module `ops` will be compiled as a pytorch extension, but only x86 code will be compiled. The compiled ops can be executed on CPU only.
 
-1. Finish above common steps
+2. Full version (CUDA ops)
 
-2. Set up environment variables
+   Both x86 and CUDA codes of `ops` module will be compiled. The compiled version can be run on both CPU and CUDA-enabled GPU (if implemented).
 
-   ```shell
-   $env:MMCV_WITH_OPS = 1
-   $env:MAX_JOBS = 8  # based on your available number of CPU cores and amount of memory
-   ```
+###### CPU version
 
-3. Following build steps of the lite version
+1. Set up environment variables
 
-   ```shell
-   # activate environment
-   conda activate mmcv
-   # change directory
-   cd mmcv
-   # build
-   python setup.py build_ext # if success, cl will be launched to compile ops
-   # install
-   python setup.py develop
-   # check
-   pip list
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> $env:MMCV_WITH_OPS = 1
    ```
 
-##### Option 3: Build MMCV (full version with CUDA)
+2. Build and install
 
-1. Finish above common steps
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> python setup.py build_ext
+   (mmcv) PS C:\Users\xxx\mmcv> python setup.py develop
+   ```
+
+###### GPU version
 
 2. Make sure `CUDA_PATH` or `CUDA_HOME` is already set in `envs` via `ls env:`, desired output is shown as below:
 
-   ```none
-   (base) PS C:\Users\WRH> ls env:
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> ls env:
 
    Name                           Value
    ----                           -----
-   <... omit some lines ...>
    CUDA_PATH                      C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2
    CUDA_PATH_V10_1                C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.1
    CUDA_PATH_V10_2                C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2
-   <... omit some lines ...>
    ```
 
    This should already be done by CUDA installer. If not, or you have multiple version of CUDA toolkit installed, set it with
 
-   ```shell
-   $env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2"
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> $env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2"
    # OR
-   $env:CUDA_HOME = $env:CUDA_PATH_V10_2 # if CUDA_PATH_V10_2 is in envs:
+   (mmcv) PS C:\Users\xxx\mmcv> $env:CUDA_HOME = $env:CUDA_PATH_V10_2 # if CUDA_PATH_V10_2 is in envs:
    ```
 
 3. Set CUDA target arch
 
    ```shell
-   # Suppose you are using GTX 1080, which is of capability 6.1
-   $env:TORCH_CUDA_ARCH_LIST="6.1"
-   # OR build all supported arch, will be slow
-   $env:TORCH_CUDA_ARCH_LIST="3.5 3.7 5.0 5.2 6.0 6.1 7.0 7.5"
+   # Here you need to change to the target architecture corresponding to your GPU
+   (mmcv) PS C:\Users\xxx\mmcv> $env:TORCH_CUDA_ARCH_LIST="7.5"
    ```
 
-```{note}
-Check your the compute capability of your GPU from [here](https://developer.nvidia.com/cuda-gpus).
-```
+   :::{note}
+   Check your the compute capability of your GPU from [here](https://developer.nvidia.com/cuda-gpus).
 
-4. Launch compiling the same way as CPU
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> &"C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2\extras\demo_suite\deviceQuery.exe"
+   Device 0: "NVIDIA GeForce GTX 1660 SUPER"
+   CUDA Driver Version / Runtime Version          11.7 / 11.1
+   CUDA Capability Major/Minor version number:    7.5
+   ```
 
-   ```shell
-   $env:MMCV_WITH_OPS = 1
-   $env:MAX_JOBS = 8  # based on available number of CPU cores and amount of memory
-   # activate environment
-   conda activate mmcv
-   # change directory
-   cd mmcv
+   The 7.5 above indicates the target architecture. Note: You need to replace v10.2 with your CUDA version in the above command.
+   :::
+
+4. Build and install
+
+   ```powershell
    # build
    python setup.py build_ext # if success, cl will be launched to compile ops
    # install
    python setup.py develop
-   # check
-   pip list
    ```
 
-```{note}
-If you are compiling against PyTorch 1.6.0, you might meet some errors from PyTorch as described in [this issue](https://github.com/pytorch/pytorch/issues/42467). Follow [this pull request](https://github.com/pytorch/pytorch/pull/43380/files) to modify the source code in your local PyTorch installation.
+   ```{note}
+   If you are compiling against PyTorch 1.6.0, you might meet some errors from PyTorch as described in [this issue](https://github.com/pytorch/pytorch/issues/42467). Follow [this pull request](https://github.com/pytorch/pytorch/pull/43380/files) to modify the source code in your local PyTorch installation.
+   ```
+
+##### Validate installation
+
+```powershell
+(mmcv) PS C:\Users\xxx\mmcv> python .dev_scripts/check_installation.py
 ```
 
-If you meet issues when running or compiling mmcv, we list some common issues in [Frequently Asked Question](../faq.html).
+If no error is reported by the above command, the installation is successful. If there is an error reported, please check [Frequently Asked Questions](../faq.md) to see if there is already a solution.
+If no solution is found, please feel free to open an [issue](https://github.com/open-mmlab/mmcv/issues).
+
+### Build mmcv
+
+If you need to use PyTorch-related modules, make sure PyTorch has been successfully installed in your environment by referring to the [PyTorch official installation guide](https://github.com/pytorch/pytorch#installation).
+
+1. Clone the repo
 
-## \[Optional\] Build MMCV on IPU machine
+   ```bash
+   git clone https://github.com/open-mmlab/mmcv.git
+   cd mmcv
+   ```
+
+2. Start building
+
+   ```bash
+   pip install -e . -v
+   ```
+
+3. Validate installation
+
+   ```bash
+   python -c 'import mmcv;print(mmcv.__version__)'
+   ```
+
+### Build mmcv-full on IPU machine
 
 Firstly, you need to apply for an IPU cloud machine, see [here](https://www.graphcore.ai/ipus-in-the-cloud).
 
-### Option 1: Docker
+#### Option 1: Docker
 
 1. Pull docker
 
-```shell
-  docker pull graphcore/pytorch
-```
+   ```bash
+   docker pull graphcore/pytorch
+   ```
 
 2. Build MMCV under same python environment
 
-### Option 2: Install from SDK
+#### Option 2: Install from SDK
 
 1. Build MMCV
 

docs/en/get_started/introduction.md

@@ -22,17 +22,17 @@ research projects as below:
 - [MMGeneration](https://github.com/open-mmlab/mmgeneration): OpenMMLab image and video generative models toolbox.
 - [MMDeploy](https://github.com/open-mmlab/mmdeploy): OpenMMLab model deployment framework.
 
-It provides the following functionalities.
+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
+- [Universal IO APIs](https://mmcv.readthedocs.io/en/latest/understand_mmcv/io.html)
+- [Image/Video processing](https://mmcv.readthedocs.io/en/latest/understand_mmcv/data_process.html)
+- [Image and annotation visualization](https://mmcv.readthedocs.io/en/latest/understand_mmcv/visualization.html)
+- [Useful utilities (progress bar, timer, ...)](https://mmcv.readthedocs.io/en/latest/understand_mmcv/utils.html)
+- [PyTorch runner with hooking mechanism](https://mmcv.readthedocs.io/en/latest/understand_mmcv/runner.html)
+- [Various CNN architectures](https://mmcv.readthedocs.io/en/latest/understand_mmcv/cnn.html)
+- [High-quality implementation of common CPU and CUDA ops](https://mmcv.readthedocs.io/en/latest/understand_mmcv/ops.html)
 
-It supports the following systems.
+It supports the following systems:
 
 - Linux
 - Windows

docs/zh_cn/conf.py

@@ -57,6 +57,8 @@ extensions = [
 
 myst_heading_anchors = 4
 
+myst_enable_extensions = ['colon_fence']
+
 autodoc_mock_imports = ['mmcv._ext', 'mmcv.utils.ext_loader', 'torchvision']
 autosectionlabel_prefix_document = True
 

docs/zh_cn/get_started/build.md

 ## 从源码编译 MMCV
 
-### 在 Linux 或者 macOS 上编译 MMCV
+### 编译 mmcv-full
 
-克隆算法库
+在编译 mmcv-full 之前，请确保 PyTorch 已经成功安装在环境中，可以参考 [PyTorch 官方安装文档](https://pytorch.org/get-started/locally/#start-locally)。可使用以下命令验证
 
 ```bash
-git clone https://github.com/open-mmlab/mmcv.git
-cd mmcv
+python -c 'import torch;print(torch.__version__)'
 ```
 
-建议安装 `ninja` 以加快编译速度
-
-```bash
-pip install -r requirements/optional.txt
+```{note}
+- 如需编译 ONNX Runtime 自定义算子，请参考[如何编译ONNX Runtime自定义算子](https://mmcv.readthedocs.io/zh_CN/latest/deployment/onnxruntime_op.html#id1)
+- 如需编译 TensorRT 自定义，请参考[如何编译MMCV中的TensorRT插件](https://mmcv.readthedocs.io/zh_CN/latest/deployment/tensorrt_plugin.html#id3)
 ```
 
-你可以安装 lite 版本
+:::{note}
+
+- 如果克隆代码仓库的速度过慢，可以使用以下命令克隆（注意：gitee 的 mmcv 不一定和 github 的保持一致，因为每天只同步一次）
 
 ```bash
-pip install -e .
+git clone https://gitee.com/open-mmlab/mmcv.git
 ```
 
-也可以安装 full 版本
+- 如果打算使用 `opencv-python-headless` 而不是 `opencv-python`，例如在一个很小的容器环境或者没有图形用户界面的服务器中，你可以先安装 `opencv-python-headless`，这样在安装 mmcv 依赖的过程中会跳过 `opencv-python`。
+
+- 如果编译过程安装依赖库的时间过长，可以[设置 pypi 源](https://mirrors.tuna.tsinghua.edu.cn/help/pypi/)
 
 ```bash
-MMCV_WITH_OPS=1 pip install -e .
+pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
 ```
 
-如果是在 macOS 上编译，则需要在安装命令前添加一些环境变量
+:::
 
-```bash
-CC=clang CXX=clang++ CFLAGS='-stdlib=libc++'
-```
+#### 在 Linux 上编译 mmcv-full
 
-例如
+| TODO: 视频教程
 
-```bash
-CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' MMCV_WITH_OPS=1 pip install -e .
-```
+1. 克隆代码仓库
 
-```{note}
-如果你打算使用 `opencv-python-headless` 而不是 `opencv-python`，例如在一个很小的容器环境或者没有图形用户界面的服务器中，你可以先安装 `opencv-python-headless`，这样在安装 mmcv 依赖的过程中会跳过 `opencv-python`
-```
+   ```bash
+   git clone https://github.com/open-mmlab/mmcv.git
+   cd mmcv
+   ```
 
-### 在 Windows 上编译 MMCV
+2. 安装 `ninja` 和 `psutil` 以加快编译速度
 
-在 Windows 上编译 MMCV 比 Linux 复杂，本节将一步步介绍如何在 Windows 上编译 MMCV。
+   ```bash
+   pip install -r requirements/optional.txt
+   ```
 
-#### 依赖项
+3. 检查 nvcc 的版本（要求大于等于 9.2，如果没有 GPU，可以跳过）
 
-请首先安装以下的依赖项：
+   ```bash
+   nvcc --version
+   ```
 
-- [Git](https://git-scm.com/download/win)：安装期间，请选择 **add git to Path**
-- [Visual Studio Community 2019](https://visualstudio.microsoft.com)：用于编译 C++ 和 CUDA 代码
-- [Miniconda](https://docs.conda.io/en/latest/miniconda.html)：包管理工具
-- [CUDA 10.2](https://developer.nvidia.com/cuda-10.2-download-archive)：如果只需要 CPU 版本可以不安装 CUDA，安装CUDA时，可根据需要进行自定义安装。如果已经安装新版本的显卡驱动，建议取消驱动程序的安装
+   上述命令如果输出以下信息，表示 nvcc 的设置没有问题，否则需要设置 CUDA_HOME
 
-```{note}
-您需要知道如何在 Windows 上设置变量环境，尤其是 "PATH" 的设置，以下安装过程都会用到。
-```
+   ```
+   nvcc: NVIDIA (R) Cuda compiler driver
+   Copyright (c) 2005-2020 NVIDIA Corporation
+   Built on Mon_Nov_30_19:08:53_PST_2020
+   Cuda compilation tools, release 11.2, V11.2.67
+   Build cuda_11.2.r11.2/compiler.29373293_0
+   ```
 
-#### 设置 Python 环境
+   :::{note}
+   如果想要支持 ROCm，可以参考 [AMD ROCm](https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html) 安装 ROCm。
+   :::
 
-1. 从 Windows 菜单启动 Anaconda 命令行
+4. 检查 gcc 的版本（要求大于等于**5.4**）
 
-```{note}
-如 Miniconda 安装程序建议，不要使用原始的 `cmd.exe` 或是 `powershell.exe`。命令行有两个版本，一个基于 PowerShell，一个基于传统的 `cmd.exe`。请注意以下说明都是使用的基于 PowerShell
-```
+   ```bash
+   gcc --version
+   ```
 
-2. 创建一个新的 Conda 环境
+5. 开始编译（预估耗时 10 分钟）
 
-   ```shell
-   conda create --name mmcv python=3.7  # 经测试，3.6, 3.7, 3.8 也能通过
-   conda activate mmcv  # 确保做任何操作前先激活环境
+   ```bash
+   MMCV_WITH_OPS=1 pip install -e . -v
    ```
 
-3. 安装 PyTorch 时，可以根据需要安装支持 CUDA 或不支持 CUDA 的版本
+6. 验证安装
 
-   ```shell
-   # CUDA version
-   conda install pytorch torchvision cudatoolkit=10.2 -c pytorch
-   # CPU version
-   conda install pytorch torchvision cpuonly -c pytorch
+   ```bash
+   python .dev_scripts/check_installation.py
    ```
 
-4. 准备 MMCV 源代码
+   如果上述命令没有报错，说明安装成功。如有报错，请查看[问题解决页面](https://mmcv.readthedocs.io/zh_CN/latest/faq.html)是否已经有解决方案。
+
+   如果没有找到解决方案，欢迎提 [issue](https://github.com/open-mmlab/mmcv/issues)。
 
-   ```shell
+#### 在 macOS 上编译 mmcv-full
+
+| TODO: 视频教程
+
+```{note}
+如果你使用的 mac 是 M1 芯片，请安装 PyTorch 的 nightly 版本，否则会遇到 [issues#2218](https://github.com/open-mmlab/mmcv/issues/2218) 中的问题。
+```
+
+1. 克隆代码仓库
+
+   ```bash
    git clone https://github.com/open-mmlab/mmcv.git
    cd mmcv
    ```
 
-5. 安装所需 Python 依赖包
+2. 安装 `ninja` 和 `psutil` 以加快编译速度
 
-   ```shell
-   pip3 install -r requirements/runtime.txt
+   ```bash
+   pip install -r requirements/optional.txt
    ```
 
-6. 建议安装 `ninja` 以加快编译速度
+3. 开始编译
 
    ```bash
-   pip install -r requirements/optional.txt
+   MMCV_WITH_OPS=1 pip install -e .
    ```
 
-#### 编译与安装 MMCV
+4. 验证安装
+
+   ```bash
+   python .dev_scripts/check_installation.py
+   ```
 
-MMCV 有三种安装的模式：
+   如果上述命令没有报错，说明安装成功。如有报错，请查看[问题解决页面](../faq.md)是否已经有解决方案。
 
-1. Lite 版本（不包含算子）
+   如果没有找到解决方案，欢迎提 [issue](https://github.com/open-mmlab/mmcv/issues)。
 
-   这种方式下，没有算子被编译，这种模式的 mmcv 是原生的 python 包
+#### 在 Windows 上编译 mmcv-full
 
-2. Full 版本（只包含 CPU 算子）
+| TODO: 视频教程
 
-   编译 CPU 算子，但只有 x86 将会被编译，并且编译版本只能在 CPU only 情况下运行
+在 Windows 上编译 mmcv-full 比 Linux 复杂，本节将一步步介绍如何在 Windows 上编译 mmcv-full。
 
-3. Full 版本（既包含 CPU 算子，又包含 CUDA 算子）
+##### 依赖项
 
-   同时编译 CPU 和 CUDA 算子，`ops` 模块的 x86 与 CUDA 的代码都可以被编译。同时编译的版本可以在 CUDA 上调用 GPU
+请先安装以下的依赖项：
+
+- [Git](https://git-scm.com/download/win)：安装期间，请选择 **add git to Path**
+- [Visual Studio Community 2019](https://visualstudio.microsoft.com)：用于编译 C++ 和 CUDA 代码
+- [Miniconda](https://docs.conda.io/en/latest/miniconda.html)：包管理工具
+- [CUDA 10.2](https://developer.nvidia.com/cuda-10.2-download-archive)：如果只需要 CPU 版本可以不安装 CUDA，安装 CUDA 时，可根据需要进行自定义安装。如果已经安装新版本的显卡驱动，建议取消驱动程序的安装
+
+```{note}
+如果不清楚如何安装以上依赖，请参考[Windows 环境从零安装 mmcv-full](https://zhuanlan.zhihu.com/p/434491590)。
+另外，你需要知道如何在 Windows 上设置变量环境，尤其是 "PATH" 的设置，以下安装过程都会用到。
+```
 
 ##### 通用步骤
 
-1. 设置 MSVC 编译器
+1. 从 Windows 菜单启动 Anaconda 命令行
+
+   如 Miniconda 安装程序建议，不要使用原始的 `cmd.exe` 或是 `powershell.exe`。命令行有两个版本，一个基于 PowerShell，一个基于传统的 `cmd.exe`。请注意以下说明都是使用的基于 PowerShell
+
+2. 创建一个新的 Conda 环境
+
+   ```powershell
+   (base) PS C:\Users\xxx> conda create --name mmcv python=3.7
+   (base) PS C:\Users\xxx> conda activate mmcv  # 确保做任何操作前先激活环境
+   ```
+
+3. 安装 PyTorch 时，可以根据需要安装支持 CUDA 或不支持 CUDA 的版本
+
+   ```powershell
+   # CUDA version
+   (mmcv) PS C:\Users\xxx> conda install pytorch torchvision cudatoolkit=10.2 -c pytorch
+   # CPU version
+   (mmcv) PS C:\Users\xxx> conda install install pytorch torchvision cpuonly -c pytorch
+   ```
+
+4. 克隆代码仓库
+
+   ```powershell
+   (mmcv) PS C:\Users\xxx> git clone https://github.com/open-mmlab/mmcv.git
+   (mmcv) PS C:\Users\xxx> cd mmcv
+   ```
+
+5. 安装 `ninja` 和 `psutil` 以加快编译速度
+
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> pip install -r requirements/optional.txt
+   ```
+
+6. 安装 mmcv 依赖
+
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> pip install -r requirements/runtime.txt
+   ```
+
+7. 设置 MSVC 编译器
 
    设置环境变量。添加 `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.27.29110\bin\Hostx86\x64` 到 `PATH`，则 `cl.exe` 可以在命令行中运行，如下所示。
 
-   ```none
-   (base) PS C:\Users\xxx> cl
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> cl
    Microsoft (R) C/C++ Optimizing  Compiler Version 19.27.29111 for x64
    Copyright (C) Microsoft Corporation.   All rights reserved.
 
@@ -137,57 +204,45 @@ MMCV 有三种安装的模式：
 
    因为 PyTorch 将解析 `cl.exe` 的输出以检查其版本，只有 utf-8 将会被识别，你可能需要将系统语言更改为英语。控制面板 -> 地区-> 管理-> 非 Unicode 来进行语言转换。
 
-##### 安装方式一：Lite version（不包含算子）
+##### 编译与安装 mmcv-full
 
-在完成上述的公共步骤后，从菜单打开 Anaconda 命令框，输入以下命令
+mmcv-full 有两个版本：
 
-```shell
-# 激活环境
-conda activate mmcv
-# 切换到 mmcv 根目录
-cd mmcv
-# 安装
-python setup.py develop
-# 检查是否安装成功
-pip list
-```
+- 只包含 CPU 算子的版本
 
-##### 安装方式二：Full version（只编译 CPU 算子）
+  编译 CPU 算子，但只有 x86 将会被编译，并且编译版本只能在 CPU only 情况下运行
 
-1. 完成上述的公共步骤
+- 既包含 CPU 算子，又包含 CUDA 算子的版本
 
-2. 设置环境变量
+  同时编译 CPU 和 CUDA 算子，`ops` 模块的 x86 与 CUDA 的代码都可以被编译。同时编译的版本可以在 CUDA 上调用 GPU
 
-   ```shell
-   $env:MMCV_WITH_OPS = 1
-   $env:MAX_JOBS = 8  # 根据你可用CPU以及内存量进行设置
-   ```
+###### CPU 版本
 
-3. 编译安装
+1. 设置环境变量
 
-   ```shell
-   conda activate mmcv  # 激活环境
-   cd mmcv  # 改变路径
-   python setup.py build_ext  # 如果成功, cl 将被启动用于编译算子
-   python setup.py develop  # 安装
-   pip list  # 检查是否安装成功
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> $env:MMCV_WITH_OPS = 1
    ```
 
-##### 安装方式三：Full version（既编译 CPU 算子又编译 CUDA 算子）
+2. 编译安装
 
-1. 完成上述的公共步骤
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> python setup.py build_ext  # 如果成功, cl 将被启动用于编译算子
+   (mmcv) PS C:\Users\xxx\mmcv> python setup.py develop  # 安装
+   ```
 
-2. 设置环境变量
+###### GPU 版本
 
-   ```shell
-   $env:MMCV_WITH_OPS = 1
-   $env:MAX_JOBS = 8  # 根据你可用CPU以及内存量进行设置
+1. 设置环境变量
+
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> $env:MMCV_WITH_OPS = 1
    ```
 
-3. 检查 `CUDA_PATH` 或者 `CUDA_HOME` 环境变量已经存在在 `envs` 之中
+2. 检查 `CUDA_PATH` 或者 `CUDA_HOME` 环境变量已经存在在 `envs` 之中
 
-   ```none
-   (base) PS C:\Users\WRH> ls env:
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> ls env:
 
    Name                           Value
    ----                           -----
@@ -198,38 +253,91 @@ pip list
 
    如果没有，你可以按照下面的步骤设置
 
-   ```shell
-   $env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2"
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> $env:CUDA_HOME = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2"
    # 或者
-   $env:CUDA_HOME = $env:CUDA_PATH_V10_2  # CUDA_PATH_V10_2 已经在环境变量中
+   (mmcv) PS C:\Users\xxx\mmcv> $env:CUDA_HOME = $env:CUDA_PATH_V10_2  # CUDA_PATH_V10_2 已经在环境变量中
    ```
 
-4. 设置 CUDA 的目标架构
+3. 设置 CUDA 的目标架构
 
-   ```shell
-   $env:TORCH_CUDA_ARCH_LIST="6.1" # 支持 GTX 1080
-   # 或者用所有支持的版本，但可能会变得很慢
-   $env:TORCH_CUDA_ARCH_LIST="3.5 3.7 5.0 5.2 6.0 6.1 7.0 7.5"
+   ```powershell
+   # 这里需要改成你的显卡对应的目标架构
+   (mmcv) PS C:\Users\xxx\mmcv> $env:TORCH_CUDA_ARCH_LIST="7.5"
    ```
 
-```{note}
-我们可以在 [here](https://developer.nvidia.com/cuda-gpus) 查看 GPU 的计算能力
-```
+   :::{note}
+   可以点击 [cuda-gpus](https://developer.nvidia.com/cuda-gpus) 查看 GPU 的计算能力，也可以通过 CUDA 目录下的 deviceQuery.exe 工具查看
 
-5. 编译安装
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> &"C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v10.2\extras\demo_suite\deviceQuery.exe"
+   Device 0: "NVIDIA GeForce GTX 1660 SUPER"
+   CUDA Driver Version / Runtime Version          11.7 / 11.1
+   CUDA Capability Major/Minor version number:    7.5
+   ```
 
-   ```shell
-   $env:MMCV_WITH_OPS = 1
-   $env:MAX_JOBS = 8 # 根据你可用CPU以及内存量进行设置
-   conda activate mmcv # 激活环境
-   cd mmcv  # 改变路径
-   python setup.py build_ext  # 如果成功, cl 将被启动用于编译算子
-   python setup.py develop # 安装
-   pip list # 检查是否安装成功
+   上面的 7.5 表示目标架构。注意：需把上面命令的 v10.2 换成你的 CUDA 版本。
+   :::
+
+4. 编译安装
+
+   ```powershell
+   (mmcv) PS C:\Users\xxx\mmcv> python setup.py build_ext  # 如果成功, cl 将被启动用于编译算子
+   (mmcv) PS C:\Users\xxx\mmcv> python setup.py develop # 安装
    ```
 
-```{note}
-如果你的 PyTorch 版本是 1.6.0，你可能会遇到一些这个 [issue](https://github.com/pytorch/pytorch/issues/42467) 提到的错误，则可以参考这个 [pull request](https://github.com/pytorch/pytorch/pull/43380/files) 修改 本地环境的 PyTorch 源代码
+   ```{note}
+   如果你的 PyTorch 版本是 1.6.0，你可能会遇到一些 [issue](https://github.com/pytorch/pytorch/issues/42467) 提到的错误，你可以参考这个 [pull request](https://github.com/pytorch/pytorch/pull/43380/files) 修改本地环境的 PyTorch 源代码
+   ```
+
+##### 验证安装
+
+```powershell
+(mmcv) PS C:\Users\xxx\mmcv> python .dev_scripts/check_installation.py
 ```
 
-如果编译安装 mmcv 的过程中遇到了问题，你也许可以在 [Frequently Asked Question](../faq.html) 找到解决方法
+如果上述命令没有报错，说明安装成功。如有报错，请查看[问题解决页面](../faq.md)是否已经有解决方案。
+如果没有找到解决方案，欢迎提 [issue](https://github.com/open-mmlab/mmcv/issues)。
+
+### 编译 mmcv
+
+如果你需要使用和 PyTorch 相关的模块，请确保 PyTorch 已经成功安装在环境中，可以参考 [PyTorch 官方安装文档](https://pytorch.org/get-started/locally/#start-locally)。
+
+1. 克隆代码仓库
+
+   ```bash
+   git clone https://github.com/open-mmlab/mmcv.git
+   cd mmcv
+   ```
+
+2. 开始编译
+
+   ```bash
+   pip install -e . -v
+   ```
+
+3. 验证安装
+
+   ```bash
+   python -c 'import mmcv;print(mmcv.__version__)'
+   ```
+
+### 在 IPU 机器编译 mmcv
+
+首先你需要有可用的 IPU 云机器，可以查看[这里](https://www.graphcore.ai/ipus-in-the-cloud)。
+
+#### 选项1: 使用 Docker
+
+1. 拉取镜像
+
+   ```bash
+   docker pull graphcore/pytorch
+   ```
+
+2. 编译 mmcv
+
+#### 选项2: 使用 SDK
+
+1. 编译 mmcv
+
+2. 参考 [IPU PyTorch document](https://docs.graphcore.ai/projects/poptorch-user-guide/en/latest/installation.html) 安装 sdk。

docs/zh_cn/get_started/introduction.md

@@ -21,15 +21,15 @@ MMCV 是一个面向计算机视觉的基础库，它支持了很多开源项目
 - [MMGeneration](https://github.com/open-mmlab/mmgeneration): OpenMMLab 图片视频生成模型工具箱
 - [MMDeploy](https://github.com/open-mmlab/mmdeploy): OpenMMLab 模型部署框架
 
-MMCV 提供了如下众多功能：
+MMCV 提供了以下功能：
 
-- 通用的 IO 接口
-- 图像和视频处理
-- 图像和标注结果可视化
-- 常用小工具（进度条，计时器等）
-- 基于 PyTorch 的通用训练框架
-- 多种 CNN 网络结构
-- 高质量实现的常见 CUDA 算子
+- [通用的 IO 接口](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/io.html)
+- [图像和视频处理](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/data_process.html)
+- [图像和标注结果可视化](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/visualization.html)
+- [常用小工具（进度条，计时器等）](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/utils.html)
+- [基于 PyTorch 的通用训练框架](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/runner.html)
+- [多种 CNN 网络结构](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/cnn.html)
+- [高质量实现的 CPU 和 CUDA 算子](https://mmcv.readthedocs.io/zh_CN/latest/understand_mmcv/ops.html)
 
 MMCV 支持以下的系统：
 
@@ -37,7 +37,7 @@ MMCV 支持以下的系统：
 - Windows
 - macOS
 
-如想了解更多特性和使用，请参考[文档](https://mmcv.readthedocs.io/zh_CN/latest)。
+欢迎查看[文档](http://mmcv.readthedocs.io/zh_CN/latest)了解更多特性和用法。
 
 ```{note}
 MMCV 需要 Python 3.6 以上版本。

requirements/optional.txt

 ninja
+psutil