[Docs] Replace markdownlint with mdformat for avoiding installing ruby (

#1936) * Use mdformat pre-commit hook * allows consecutive numbering * improve .mdformat.toml * test mdformat * format markdown * minor fix * fix codespecll * fix circleci * add linkify-it-py dependency for cicleci * add comments * replace flake8 url * add mdformat-myst dependency * remove mdformat-myst dependency * update contributing.md
open-mmlab · May 16, 2022 · b326a21 · b326a21
1 parent 8708851
commit b326a21
Show file tree

Hide file tree

Showing 41 changed files with 1,377 additions and 1,368 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -5,12 +5,6 @@ jobs:
       - image: cimg/python:3.7.4
     steps:
       - checkout
-      - run:
-          name: Install dependencies
-          command: |
-            sudo apt-add-repository ppa:brightbox/ruby-ng -y
-            sudo apt-get update
-            sudo apt-get install -y ruby2.7
       - run:
           name: Install pre-commit hook
           command: |

diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -4,15 +4,14 @@ about: Suggest an idea for this project
 title: ''
 labels: ''
 assignees: ''
-
 ---
 
 **Describe the feature**
 
 **Motivation**
 A clear and concise description of the motivation of the feature.
-Ex1. It is inconvenient when [....].
-Ex2. There is a recent paper [....], which is very helpful for [....].
+Ex1. It is inconvenient when \[....\].
+Ex2. There is a recent paper \[....\], which is very helpful for \[....\].
 
 **Related resources**
 If there is an official code release or third-party implementations, please also provide the information here, which would be very helpful.

diff --git a/.github/ISSUE_TEMPLATE/general_questions.md b/.github/ISSUE_TEMPLATE/general_questions.md
@@ -4,7 +4,6 @@ about: Ask general questions to get help
 title: ''
 labels: ''
 assignees: ''
-
 ---
 
 **Checklist**

diff --git a/.github/ISSUE_TEMPLATE/unexpected_report.md b/.github/ISSUE_TEMPLATE/unexpected_report.md
@@ -4,7 +4,6 @@ about: Create a report to help us improve
 title: ''
 labels: ''
 assignees: ''
-
 ---
 
 Thanks for reporting the unexpected results and we appreciate it a lot.
@@ -32,8 +31,8 @@ A placeholder for the command.
 
 1. Please run `python -c "from mmcv.utils import collect_env; print(collect_env())"` to collect necessary environment information and paste it here.
 2. You may add addition that may be helpful for locating the problem, such as
-    - How you installed PyTorch [e.g., pip, conda, source]
-    - Other environment variables that may be related (such as `$PATH`, `$LD_LIBRARY_PATH`, `$PYTHONPATH`, etc.)
+   - How you installed PyTorch \[e.g., pip, conda, source\]
+   - Other environment variables that may be related (such as `$PATH`, `$LD_LIBRARY_PATH`, `$PYTHONPATH`, etc.)
 
 **Error traceback**
 If applicable, paste the error traceback here.

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 exclude: ^tests/data/
 repos:
-  - repo: https://gitlab.com/pycqa/flake8.git
+  - repo: https://github.com/PyCQA/flake8
     rev: 3.8.3
     hooks:
       - id: flake8
@@ -25,16 +25,19 @@ repos:
         args: ["--remove"]
       - id: mixed-line-ending
         args: ["--fix=lf"]
-  - repo: https://github.com/markdownlint/markdownlint
-    rev: v0.11.0
-    hooks:
-      - id: markdownlint
-        args: ["-r", "~MD002,~MD013,~MD029,~MD033,~MD034",
-              "-t", "allow_different_nesting"]
   - repo: https://github.com/codespell-project/codespell
     rev: v2.1.0
     hooks:
       - id: codespell
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
+    hooks:
+      - id: mdformat
+        args: ["--number"]
+        additional_dependencies:
+          - mdformat-gfm
+          - mdformat_frontmatter
+          - linkify-it-py
   - repo: https://github.com/myint/docformatter
     rev: v1.3.1
     hooks:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -16,6 +16,7 @@ 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
 
 #### Python
@@ -24,10 +25,11 @@ We adopt [PEP8](https://www.python.org/dev/peps/pep-0008/) as the preferred code
 
 We use the following tools for linting and formatting:
 
-- [flake8](http://flake8.pycqa.org/en/latest/): A wrapper around some linter tools.
-- [yapf](https://github.com/google/yapf): A formatter for Python files.
+- [flake8](https://github.com/PyCQA/flake8): A wrapper around some linter tools.
 - [isort](https://github.com/timothycrosley/isort): A Python utility to sort imports.
-- [markdownlint](https://github.com/markdownlint/markdownlint): A linter to check markdown files and flag style issues.
+- [yapf](https://github.com/google/yapf): A formatter for Python files.
+- [codespell](https://github.com/codespell-project/codespell): A Python utility to fix common misspellings in text files.
+- [mdformat](https://github.com/executablebooks/mdformat): Mdformat is an opinionated Markdown formatter that can be used to enforce a consistent style in Markdown files.
 - [docformatter](https://github.com/myint/docformatter): A formatter to format docstring.
 
 Style configurations of yapf and isort can be found in [setup.cfg](./setup.cfg).
@@ -48,23 +50,9 @@ From the repository folder
 pre-commit install
 ```
 
-Try the following steps to install ruby when you encounter an issue on installing markdownlint
-
-```shell
-# install rvm
-curl -L https://get.rvm.io | bash -s -- --autolibs=read-fail
-[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"
-rvm autolibs disable
-
-# install ruby
-rvm install 2.7.1
-```
-
-Or refer to [this repo](https://github.com/innerlee/setup) and take [`zzruby.sh`](https://github.com/innerlee/setup/blob/master/zzruby.sh) according its instruction.
-
 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.
+> Before you create a PR, make sure that your code lints and is formatted by yapf.
 
 #### C++ and CUDA
 

diff --git a/LICENSES.md b/LICENSES.md
@@ -2,7 +2,7 @@
 
 In this file, we list the operations with other licenses instead of Apache 2.0. Users should be careful about adopting these operations in any commercial matters.
 
-|    Operation     |                                                                    Files                                                                              |    License     |
-| :--------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------: | :------------: |
+|    Operation     |                                                                               Files                                                                               |    License     |
+| :--------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------: |
 |    upfirdn2d     |          [mmcv/ops/csrc/pytorch/cuda/upfirdn2d_kernel.cu](https://github.com/open-mmlab/mmcv/blob/master/mmcv/ops/csrc/pytorch/cuda/upfirdn2d_kernel.cu)          | NVIDIA License |
 | fused_leaky_relu | [mmcv/ops/csrc/pytorch/cuda/fused_bias_leakyrelu_cuda.cu](https://github.com/open-mmlab/mmcv/blob/master/mmcv/ops/csrc/pytorch/cuda/fused_bias_leakyrelu_cuda.cu) | NVIDIA License |
diff --git a/README.md b/README.md
@@ -77,7 +77,7 @@ Note: MMCV requires Python 3.6+.
 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.
+- **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 version is highly recommended if CUDA is available`.
 
@@ -89,14 +89,14 @@ We provide pre-built mmcv packages (recommended) with different PyTorch and CUDA
 
 i. Install the latest version.
 
-The rule for installing the latest ``mmcv-full`` is as follows:
+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.1`` and ``PyTorch 1.9.0``, use the following command:
+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.1` and `PyTorch 1.9.0`, use the following command:
 
 ```shell
 pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
@@ -108,19 +108,19 @@ pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9
 pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html
 ```
 
-For more details, please refer the the following tables and delete ``=={mmcv_version}``.
+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:
+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.3.9``.
-Then replace ``{cu_version}`` and ``{torch_version}`` in the url to your desired versions. For example,
-to install ``mmcv-full==1.3.9`` with ``CUDA 11.1`` and ``PyTorch 1.9.0``, use the following command:
+First of all, please refer to the Releases and replace `{mmcv_version}` a specified one. e.g. `1.3.9`.
+Then replace `{cu_version}` and `{torch_version}` in the url to your desired versions. For example,
+to install `mmcv-full==1.3.9` with `CUDA 11.1` and `PyTorch 1.9.0`, use the following command:
 
 ```shell
 pip install mmcv-full==1.3.9 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html

diff --git a/README_zh-CN.md b/README_zh-CN.md
@@ -88,13 +88,13 @@ a. 安装完整版
 
 i. 安装最新版本
 
-如下是安装最新版 ``mmcv-full`` 的命令
+如下是安装最新版 `mmcv-full` 的命令
 
 ```shell
 pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
 ```
 
-请将链接中的 ``{cu_version}`` 和 ``{torch_version}`` 根据自身需求替换成实际的版本号，例如想安装和 ``CUDA 11.1``、``PyTorch 1.9.0`` 兼容的最新版 ``mmcv-full``，使用如下替换过的命令
+请将链接中的 `{cu_version}` 和 `{torch_version}` 根据自身需求替换成实际的版本号，例如想安装和 `CUDA 11.1`、`PyTorch 1.9.0` 兼容的最新版 `mmcv-full`，使用如下替换过的命令
 
 ```shell
 pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
@@ -106,18 +106,18 @@ pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9
 pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.8.0/index.html
 ```
 
-如果想知道更多 CUDA 和 PyTorch 版本的命令，可以参考下面的表格，将链接中的 ``=={mmcv_version}`` 删去即可。
+如果想知道更多 CUDA 和 PyTorch 版本的命令，可以参考下面的表格，将链接中的 `=={mmcv_version}` 删去即可。
 
 ii. 安装特定的版本
 
-如下是安装特定版本 ``mmcv-full`` 的命令
+如下是安装特定版本 `mmcv-full` 的命令
 
 ```shell
 pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html
 ```
 
-首先请参考版本发布信息找到想要安装的版本号，将 ``{mmcv_version}`` 替换成该版本号，例如 ``1.3.9``。
-然后将链接中的 ``{cu_version}`` 和 ``{torch_version}`` 根据自身需求替换成实际的版本号，例如想安装和 ``CUDA 11.1``、``PyTorch 1.9.0`` 兼容的 ``mmcv-full`` 1.3.9 版本，使用如下替换过的命令
+首先请参考版本发布信息找到想要安装的版本号，将 `{mmcv_version}` 替换成该版本号，例如 `1.3.9`。
+然后将链接中的 `{cu_version}` 和 `{torch_version}` 根据自身需求替换成实际的版本号，例如想安装和 `CUDA 11.1`、`PyTorch 1.9.0` 兼容的 `mmcv-full` 1.3.9 版本，使用如下替换过的命令
 
 ```shell
 pip install mmcv-full==1.3.9 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html
@@ -255,6 +255,7 @@ c. 安装完整版并且编译 onnxruntime 的自定义算子
 ## 许可证
 
 `MMCV` 目前以 Apache 2.0 的许可证发布，但是其中有一部分功能并不是使用的 Apache2.0 许可证，我们在 [许可证](LICENSES.md) 中详细地列出了这些功能以及他们对应的许可证，如果您正在从事盈利性活动，请谨慎参考此文档。
+
 ## 欢迎加入 OpenMMLab 社区
 
 扫描下方的二维码可关注 OpenMMLab 团队的 [知乎官方账号](https://www.zhihu.com/people/openmmlab)，加入 OpenMMLab 团队的 [官方交流 QQ 群](https://jq.qq.com/?_wv=1027&k=3ijNTqfg)，或添加微信小助手”OpenMMLabwx“加入官方交流微信群。

diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md
@@ -4,27 +4,27 @@ This document is used as a reference for English-Chinese terminology translation
 
 该文档用作中英文翻译对照参考。
 
-| English | 中文 |
-| :-----: | :---:|
-| annotation | 标注 |
-| backbone | 主干网络 |
-| benchmark | 基准测试 |
-| checkpoint | 模型权重文件 |
-| classifier | 分类器 |
-| cls_head | 分类头 |
-| decoder | 解码器 |
-| detector | 检测器 |
-| encoder | 编码器 |
-| finetune | 微调 |
-| ground truth | 真实标签 |
-| hook | 钩子 |
-| localizer | 定位器 |
-| neck | 模型颈部 |
-| pipeline | 流水线 |
-| recognizer | 识别器 |
-| register | 注册器 |
-| schedule | 调整 |
-| scheduler | 调度器 |
-| segmentor | 分割器 |
-| tensor | 张量 |
-| training schedule | 训练策略 |
+|      English      |   中文   |
+| :---------------: | :----: |
+|    annotation     |   标注   |
+|     backbone      |  主干网络  |
+|     benchmark     |  基准测试  |
+|    checkpoint     | 模型权重文件 |
+|    classifier     |  分类器   |
+|     cls_head      |  分类头   |
+|      decoder      |  解码器   |
+|     detector      |  检测器   |
+|      encoder      |  编码器   |
+|     finetune      |   微调   |
+|   ground truth    |  真实标签  |
+|       hook        |   钩子   |
+|     localizer     |  定位器   |
+|       neck        |  模型颈部  |
+|     pipeline      |  流水线   |
+|    recognizer     |  识别器   |
+|     register      |  注册器   |
+|     schedule      |   调整   |
+|     scheduler     |  调度器   |
+|     segmentor     |  分割器   |
+|      tensor       |   张量   |
+| training schedule |  训练策略  |
diff --git a/docs/en/community/pr.md b/docs/en/community/pr.md
@@ -21,10 +21,10 @@ Pull requests let you tell others about changes you have pushed to a branch in a
 
 #### 1. Get the most recent codebase
 
-+ When you work on your first PR
+- When you work on your first PR
 
   Fork the OpenMMLab repository: click the **fork** button at the top right corner of Github page
-    ![avatar](../_static/community/1.png)
+  ![avatar](../_static/community/1.png)
 
   Clone forked repository to local
 
@@ -38,14 +38,14 @@ Pull requests let you tell others about changes you have pushed to a branch in a
   git remote add upstream [email protected]:open-mmlab/mmcv
   ```
 
-+ After your first PR
+- After your first PR
 
-    Checkout master branch of the local repository and pull the latest master branch of the source repository
+  Checkout master branch of the local repository and pull the latest master branch of the source repository
 
-    ```bash
-    git checkout master
-    git pull upstream master
-    ```
+  ```bash
+  git checkout master
+  git pull upstream master
+  ```
 
 #### 2. Checkout a new branch from the master branch
 
@@ -67,23 +67,23 @@ git commit -m 'messages'
 
 #### 4. Push your changes to the forked repository and create a PR
 
-+ Push the branch to your forked remote repository
+- Push the branch to your forked remote repository
 
-    ```bash
-    git push origin branchname
-    ```
+  ```bash
+  git push origin branchname
+  ```
 
-+ Create a PR
-![avatar](../_static/community/2.png)
+- Create a PR
+  ![avatar](../_static/community/2.png)
 
-+ Revise PR message template to describe your motivation and modifications made in this PR. You can also link the related issue to the PR manually in the PR message (For more information, checkout the [official guidance](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)).
+- Revise PR message template to describe your motivation and modifications made in this PR. You can also link the related issue to the PR manually in the PR message (For more information, checkout the [official guidance](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)).
 
 #### 5. Discuss and review your code
 
-+ After creating a pull request, you can ask a specific person to review the changes you've proposed
-![avatar](../_static/community/3.png)
+- After creating a pull request, you can ask a specific person to review the changes you've proposed
+  ![avatar](../_static/community/3.png)
 
-+ Modify your codes according to reviewers' suggestions and then push your changes
+- Modify your codes according to reviewers' suggestions and then push your changes
 
 #### 6.  Merge your branch to the master branch and delete the branch
 
@@ -100,15 +100,15 @@ git push origin --delete branchname # delete remote branch
 
 3. Accomplish a detailed change in one PR. Avoid large PR
 
-   + Bad: Support Faster R-CNN
-   + Acceptable: Add a box head to Faster R-CNN
-   + Good: Add a parameter to box head to support custom conv-layer number
+   - Bad: Support Faster R-CNN
+   - Acceptable: Add a box head to Faster R-CNN
+   - Good: Add a parameter to box head to support custom conv-layer number
 
 4. Provide clear and significant commit message
 
 5. Provide clear and meaningful PR description
 
-   + Task name should be clarified in title. The general format is: [Prefix] Short description of the PR (Suffix)
-   + Prefix: add new feature [Feature], fix bug [Fix], related to documents [Docs], in developing [WIP] (which will not be reviewed temporarily)
-   + Introduce main changes, results and influences on other modules in short description
-   + Associate related issues and pull requests with a milestone
+   - Task name should be clarified in title. The general format is: \[Prefix\] Short description of the PR (Suffix)
+   - Prefix: add new feature \[Feature\], fix bug \[Fix\], related to documents \[Docs\], in developing \[WIP\] (which will not be reviewed temporarily)
+   - Introduce main changes, results and influences on other modules in short description
+   - Associate related issues and pull requests with a milestone