Refactor docs

docs/CONTRIBUTING.md → .github/CONTRIBUTING.md

@@ -15,7 +15,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.
 - If you are the author of some papers and would like to include your method to mmdetection,
-please contact Wenwei Zhang (zwwdev[at]gmail[dot]com). We will much appreciate your contribution.
+please contact Kai Chen (chenkaidev[at]gmail[dot]com) and Wenwei Zhang (zwwdev[at]gmail[dot]com). We will much appreciate your contribution.
 
 ## Code style
 
@@ -27,7 +27,25 @@ We use the following tools for linting and formatting:
 - [yapf](https://github.com/google/yapf): formatter
 - [isort](https://github.com/timothycrosley/isort): sort imports
 
-Style configurations of yapf and isort can be found in [.style.yapf](.style.yapf) and [.isort.cfg](.isort.cfg).
+Style configurations of yapf and isort can be found in [.style.yapf](../.style.yapf) and [.isort.cfg](../.isort.cfg).
+
+We use [pre-commit hook](https://pre-commit.com/) that checks and formats for `flake8`, `yapf`, `isort`, `trailing whitespaces`,
+ fixes `end-of-files`, sorts `requirments.txt` automatically on every commit.
+The config for a pre-commit hook is stored in [.pre-commit-config](../.pre-commit-config.yaml).
+
+After you clone the repository, you will need to install initialize pre-commit hook.
+
+```
+pip install -U pre-commit
+```
+
+From the repository folder
+```
+pre-commit install
+```
+
+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.
 

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/error-report.md

@@ -0,0 +1,41 @@
+---
+name: Error report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+Thanks for your error report and we appreciate it a lot.
+
+**Checklist**
+1. I have searched related issues but cannot get the expected help.
+2. The bug has not been fixed in the latest version.
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Reproduction**
+1. What command or script did you run?
+```
+A placeholder for the command.
+```
+2. Did you make any modifications on the code or config? Did you understand what you have modified?
+3. What dataset did you use?
+
+**Environment**
+
+1. Please run `python mmdet/utils/collect_env.py` to collect necessary environment infomation 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.)
+
+**Error traceback**
+If applicable, paste the error trackback here.
+```
+A placeholder for trackback.
+```
+
+**Bug fix**
+If you have already identified the reason, you can provide the information here. If you are willing to create a PR to fix it, please also leave a comment here and that would be much appreciated!

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+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 [....].
+
+**Related resources**
+If there is an official code release or third-party implementations, please also provide the information here, which would be very helpful.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
+If you would like to implement the feature and create a PR, please leave a comment here and that would be much appreciated.

.github/ISSUE_TEMPLATE/general_questions.md

@@ -0,0 +1,8 @@
+---
+name: General questions
+about: Ask general questions to get help
+title: ''
+labels: ''
+assignees: ''
+
+---

.github/ISSUE_TEMPLATE/reimplementation_questions.md

@@ -0,0 +1,59 @@
+---
+name: Reimplementation Questions
+about: Ask about questions during model reimplementation
+title: ''
+labels: 'reimplementation'
+assignees: ''
+
+---
+
+**Notice**
+
+There are several common situations in the reimplementation issues as below
+1. Reimplement a model in the model zoo using the provided configs
+2. Reimplement a model in the model zoo on other dataset (e.g., custom datasets)
+3. Reimplement a custom model but all the components are implemented in MMDetection
+4. Reimplement a custom model with new modules implemented by yourself
+
+There are several things to do for different cases as below.
+- For case 1 & 3, please follow the steps in the following sections thus we could help to quick identify the issue.
+- For case 2 & 4, please understand that we are not able to do much help here because we usually do not know the full code and the users should be responsible to the code they write.
+- One suggestion for case 2 & 4 is that the users should first check whether the bug lies in the self-implemted code or the original code. For example, users can first make sure that the same model runs well on supported datasets. If you still need help, please describe what you have done and what you obtain in the issue, and follow the steps in the following sections and try as clear as possible so that we can better help you.
+
+**Checklist**
+1. I have searched related issues but cannot get the expected help.
+2. The issue has not been fixed in the latest version.
+
+**Describe the issue**
+
+A clear and concise description of what the problem you meet and what have you done.
+
+**Reproduction**
+1. What command or script did you run?
+```
+A placeholder for the command.
+```
+2. What config dir you run?
+```
+A placeholder for the config.
+```
+3. Did you make any modifications on the code or config? Did you understand what you have modified?
+4. What dataset did you use?
+
+**Environment**
+
+1. Please run `python mmdet/utils/collect_env.py` to collect necessary environment infomation 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.)
+
+**Results**
+
+If applicable, paste the related results here, e.g., what you expect and what you get.
+```
+A placeholder for results comparison
+```
+
+**Issue fix**
+
+If you have already identified the reason, you can provide the information here. If you are willing to create a PR to fix it, please also leave a comment here and that would be much appreciated!

README.md

@@ -1,58 +1,100 @@
-
 # MMDetection3D
 
+**News**: We released the codebase v0.1.0.
+
+Documentation: https://mmdetection3d.readthedocs.io/
 
 ## Introduction
 
-The master branch works with **PyTorch 1.1** or higher.
+The master branch works with **PyTorch 1.3 to 1.5**.
 
-mmdetection3d is an open source 3D object detection toolbox based on PyTorch. It is
-a part of the open-mmlab project developed by [Multimedia Laboratory, CUHK](http://mmlab.ie.cuhk.edu.hk/).
+MMDetection3D is an open source object detection toolbox based on PyTorch. It is
+a part of the OpenMMLab project developed by [MMLab](http://mmlab.ie.cuhk.edu.hk/).
 
+![demo image](demo/coco_test_12510.jpg)
 
 ### Major features
 
+- **Modular Design**
+
+  We decompose the detection framework into different components and one can easily construct a customized object detection framework by combining different modules.
+
+- **Support of multiple frameworks out of box**
+
+  The toolbox directly supports popular and contemporary detection frameworks, *e.g.* Faster RCNN, Mask RCNN, RetinaNet, etc.
+
+- **High efficiency**
+
+  The training speed is [faster than other codebases](./docs/benchmarks.md).
 
+- **State of the art**
+
+  The accuracy of models is [faster than other codebases](./docs/benchmarks.md).
+
+Apart from MMDetection3D, we also released a library [MMDetection](https://github.com/open-mmlab/mmdetection) and [mmcv](https://github.com/open-mmlab/mmcv) for computer vision research, which are heavily depended on by this toolbox.
 
 ## License
 
 This project is released under the [Apache 2.0 license](LICENSE).
 
-## Updates
-
+## Changelog
 
-v0.0.1 (07/08/2019)
-- the project is initiated
+v0.1.0 was released in 24/6/2020.
+Please refer to [changelog.md](docs/changelog.md) for details and release history.
 
 ## Benchmark and model zoo
 
 Supported methods and backbones are shown in the below table.
-Results and models are available in the [Model zoo](MODEL_ZOO.md).
+Results and models are available in the [model zoo](docs/model_zoo.md).
 
+|                    | ResNet   | ResNeXt  | SENet    |PointNet++ | HRNet | RegNetX | Res2Net |
+|--------------------|:--------:|:--------:|:--------:|:---------:|:-----:|:--------:|:-----:|
+| SECOND             | ☐        | ☐        | ☐        | ✗         | ✓     | ✓        | ☐     |
+| PointPillars       | ☐        | ☐        | ☐        | ✗         | ✓     | ✓        | ☐     |
+| VoteNet            | ✗        | ✗        | ✗        | ✓         | ✗     | ✗        | ✗     |
+| Part-A2            | ☐        | ☐        | ☐        | ✗         | ✓     | ✓        | ☐     |
+| MVXNet             | ☐        | ☐        | ☐        | ✗         | ✓     | ✓        | ☐     |
+
+Other features
+- [x] [Dynamic Voxelization](configs/carafe/README.md)
+
+**Notice**: All the models or modules supported in [MMDetection's model zoo](https://github.com/open-mmlab/mmdetection/blob/master/docs/model_zoo.md) can be trained or used in this codebase.
 
 ## Installation
 
-Please refer to [INSTALL.md](INSTALL.md) for installation and dataset preparation.
+Please refer to [install.md](docs/install.md) for installation and dataset preparation.
 
 
 ## Get Started
 
-Please see [GETTING_STARTED.md](GETTING_STARTED.md) for the basic usage of MMDetection.
+Please see [getting_started.md](docs/getting_started.md) for the basic usage of MMDetection. There are also tutorials for [finetuning models](docs/tutorials/finetune.md), [adding new dataset](docs/tutorials/new_dataset.md), [designing data pipeline](docs/tutorials/data_pipeline.md), and [adding new modules](docs/tutorials/new_modules.md).
 
 ## Contributing
 
-We appreciate all contributions to improve MMDetection3D. Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for the contributing guideline.
+We appreciate all contributions to improve MMDetection. Please refer to [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the contributing guideline.
 
 ## Acknowledgement
 
 MMDetection3D is an open source project that is contributed by researchers and engineers from various colleges and companies. We appreciate all the contributors who implement their methods or add new features, as well as users who give valuable feedbacks.
-We wish that the toolbox and benchmark could serve the growing research community by providing a flexible toolkit to reimplement existing methods and develop their own new detectors.
+We wish that the toolbox and benchmark could serve the growing research community by providing a flexible toolkit to reimplement existing methods and develop their own new 3D detectors.
 
 
 ## Citation
 
+If you use this toolbox or benchmark in your research, please cite this project.
+
+```
+@misc{mmdetection3d_2020,
+  title   = {{MMDetection3D}},
+  author  = {Zhang, Wenwei and Wu, Yuefeng and Li, Yinhao and Lin, Kwan-Yee and
+             Qian, Chen, Shi, Jianping, and Chen, Kai, and Li, Hongsheng and
+             Lin, Dahua, and Loy, Chen Change},
+  howpublished = {\url{https://github.com/open-mmlab/mmdetection3d}},
+  year =         {2020}
+}
+```
 
 
 ## Contact
 
-This repo is currently maintained by Wenwei Zhang ([@ZwwWayne](http://github.com/ZwwWayne)).
+This repo is currently maintained by Wenwei Zhang ([@ZwwWayne](https://github.com/ZwwWayne)).