update docs

Summary: Pull Request resolved: fairinternal/detectron2#406

Reviewed By: rbgirshick

Differential Revision: D21499456

Pulled By: ppwwyyxx

fbshipit-source-id: f95c74c9ee126718b46fb439d9c2ee457e98a87b

.github/CONTRIBUTING.md

@@ -1,6 +1,4 @@
 # Contributing to detectron2
-We want to make contributing to this project as easy and transparent as
-possible.
 
 ## Issues
 We use GitHub issues to track public bugs and questions.
@@ -15,7 +13,7 @@ outlined on that page and do not file a public issue.
 ## Pull Requests
 We actively welcome your pull requests.
 
-However, if you're adding any significant features, please
+However, if you're adding any significant features (e.g. > 50 lines), please
 make sure to have a corresponding issue to discuss your motivation and proposals,
 before sending a PR. We do not always accept new features, and we take the following
 factors into consideration:
@@ -34,11 +32,10 @@ When sending a PR, please do:
 
 1. If a PR contains multiple orthogonal changes, split it to several PRs.
 2. If you've added code that should be tested, add tests.
-3. For PRs that need experiments (e.g. adding a new model), you don't need to update model zoo,
-   but do provide experiment results in the description of the PR.
+3. For PRs that need experiments (e.g. adding a new model or new methods),
+	 you don't need to update model zoo, but do provide experiment results in the description of the PR.
 4. If APIs are changed, update the documentation.
-5. Ensure the test suite passes.
-6. Make sure your code lints with `./dev/linter.sh`.
+5. Make sure your code lints with `./dev/linter.sh`.
 
 
 ## Contributor License Agreement ("CLA")

.github/ISSUE_TEMPLATE/bugs.md

@@ -0,0 +1,36 @@
+---
+name: "Bugs"
+about: Report bugs in detectron2
+title: Please read & provide the following
+
+---
+
+## Instructions To Reproduce the Bug:
+
+1. what changes you made (`git diff`) or what code you wrote
+```
+<put diff or code here>
+```
+2. what exact command you run:
+3. what you observed (including __full logs__):
+```
+<put logs here>
+```
+4. please simplify the steps as much as possible so they do not require additional resources to
+	 run, such as a private dataset.
+
+## Expected behavior:
+
+If there are no obvious error in "what you observed" provided above,
+please tell us the expected behavior.
+
+## Environment:
+
+Provide your environment information using the following command:
+```
+wget -nc -q https://github.com/facebookresearch/detectron2/raw/master/detectron2/utils/collect_env.py && python collect_env.py
+```
+
+If your issue looks like an installation issue / environment issue,
+please first try to solve it yourself with the instructions in
+https://detectron2.readthedocs.io/tutorials/install.html#common-installation-issues

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1,9 @@
+# require an issue template to be chosen
 blank_issues_enabled: false
+
+# Unexpected behaviors & bugs are split to two templates.
+# When they are one template, users think "it's not a bug" and don't choose the template.
+#
+# But the file name is still "unexpected-problems-bugs.md" so that old references
+# to this issue template still works.
+# It's ok since this template should be a superset of "bugs.md" (unexpected behaviors is a superset of bugs)

.github/ISSUE_TEMPLATE/feature-request.md

@@ -27,6 +27,5 @@ because they are research code release that is mainly for other researchers to r
 
 Instead of adding features inside detectron2,
 you can implement many features by [extending detectron2](https://detectron2.readthedocs.io/tutorials/extend.html).
-The [projects/](https://github.com/facebookresearch/detectron2/tree/master/projects/) directory
-contains many of such examples.
+The [projects/](https://github.com/facebookresearch/detectron2/tree/master/projects/) directory contains many of such examples.
 

.github/ISSUE_TEMPLATE/questions-help-support.md

@@ -1,27 +1,26 @@
 ---
 name: "❓How to do something?"
-about: How to do X with detectron2? How detectron2 does X?
+about: How to do something using detectron2? What does an API do?
 
 ---
 
 ## ❓ How to do something using detectron2
 
-General questions in learning detectron2, like:
-
-1. How to do X with detectron2?
-2. How detectron2 does X?
+Describe what you want to do, including:
+1. what inputs you will provide, if any:
+2. what outputs you are expecting:
 
+## ❓ What does an API do and how to use it?
+Please link to which API or documentation you're asking about from
+https://detectron2.readthedocs.io/
 
 
 NOTE:
 
-1. Only general answers are provided for how-to questions.
-   If you want to ask about "why X did not work",
-   please use the [Unexpected behaviors / Bugs](https://github.com/facebookresearch/detectron2/issues/new?template=unexpected-problems-bugs.md)
-   issue template.
+1. Only general answers are provided.
+   If you want to ask about "why X did not work", please use the
+   [Unexpected behaviors](https://github.com/facebookresearch/detectron2/issues/new/choose) issue template.
 
 2. About how to implement new models / new dataloader / new training logic, etc., check documentation first.
 
-3. We do not answer general machine learning / computer vision questions that are not specific to
-   detectron2, such as how a model works, how to improve your training/make it converge, or what algorithm/methods can be
-   used to achieve X.
+3. We do not answer general machine learning / computer vision questions that are not specific to detectron2, such as how a model works, how to improve your training/make it converge, or what algorithm/methods can be used to achieve X.

.github/ISSUE_TEMPLATE/unexpected-problems-bugs.md

@@ -1,11 +1,11 @@
 ---
-name: "Unexpected behaviors / Bugs"
-about: Report unexpected behaviors or bugs in detectron2
+name: "Unexpected behaviors"
+about: Run into unexpected behaviors when using detectron2
 title: Please read & provide the following
 
 ---
 
-If you do not know the root cause of the problem / bug, and wish someone to help you, please
+If you do not know the root cause of the problem, and wish someone to help you, please
 post according to this template:
 
 ## Instructions To Reproduce the Issue:
@@ -19,7 +19,7 @@ post according to this template:
 ```
 <put logs here>
 ```
-4. please also simplify the steps as much as possible so they do not require additional resources to
+4. please simplify the steps as much as possible so they do not require additional resources to
 	 run, such as a private dataset.
 
 ## Expected behavior:

.github/pull_request_template.md

@@ -2,7 +2,8 @@ Thanks for your contribution!
 
 If you're sending a large PR (e.g., >50 lines),
 please open an issue first about the feature / bug, and indicate how you want to contribute.
-See more at https://detectron2.readthedocs.io/notes/contributing.html#pull-requests
-about how we handle PRs.
 
 Before submitting a PR, please run `dev/linter.sh` to lint the code.
+
+See https://detectron2.readthedocs.io/notes/contributing.html#pull-requests
+about how we handle PRs.

INSTALL.md

@@ -2,7 +2,7 @@
 
 Our [Colab Notebook](https://colab.research.google.com/drive/16jcaJoc6bCFAQ96jDe2HwtXj7BMD_-m5)
 has step-by-step instructions that install detectron2.
-The [Dockerfile](docker/Dockerfile)
+The [Dockerfile](docker)
 also installs detectron2 with a few simple commands.
 
 ### Requirements
@@ -144,7 +144,7 @@ Two possibilities:
 
 <details>
 <summary>
-Undefined CUDA symbols or cannot open libcudart.so.
+Undefined CUDA symbols; cannot open libcudart.so; other nvcc failures.
 </summary>
 <br/>
 The version of NVCC you use to build detectron2 or torchvision does

detectron2/config/defaults.py

@@ -573,8 +573,9 @@
 # Directory where output files are written
 _C.OUTPUT_DIR = "./output"
 # Set seed to negative to fully randomize everything.
-# Set seed to positive to use a fixed seed. Note that a fixed seed does not
-# guarantee fully deterministic behavior.
+# Set seed to positive to use a fixed seed. Note that a fixed seed increases
+# reproducibility but does not guarantee fully deterministic behavior.
+# Disabling all parallelism further increases reproducibility.
 _C.SEED = -1
 # Benchmark different cudnn algorithms.
 # If input images have very different sizes, this option will have large overhead

detectron2/data/build.py

@@ -258,12 +258,12 @@ def build_detection_train_loader(cfg, mapper=None):
     A data loader is created by the following steps:
 
     1. Use the dataset names in config to query :class:`DatasetCatalog`, and obtain a list of dicts.
-    2. Start workers to work on the dicts. Each worker will:
-
+    2. Coordinate a random shuffle order shared among all processes (all GPUs)
+    3. Each process spawn another few workers to process the dicts. Each worker will:
        * Map each metadata dict into another format to be consumed by the model.
        * Batch them by simply putting dicts into a list.
 
-    The batched ``list[mapped_dict]`` is what this dataloader will return.
+    The batched ``list[mapped_dict]`` is what this dataloader will yield.
 
     Args:
         cfg (CfgNode): the config

detectron2/data/datasets/coco.py

@@ -384,7 +384,7 @@ def convert_to_coco_dict(dataset_name):
 
     logger.info(
         "Conversion finished, "
-        f"num images: {len(coco_images)}, num annotations: {len(coco_annotations)}"
+        f"#images: {len(coco_images)}, #annotations: {len(coco_annotations)}"
     )
 
     info = {

detectron2/layers/blocks.py

@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+# Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved
 
 from torch import nn
 

detectron2/modeling/meta_arch/semantic_seg.py

@@ -59,8 +59,10 @@ def forward(self, batched_inputs):
             list[dict]:
               Each dict is the output for one input image.
               The dict contains one key "sem_seg" whose value is a
-              Tensor of the output resolution that represents the
-              per-pixel segmentation prediction.
+              Tensor that represents the
+              per-pixel segmentation prediced by the head.
+              The prediction has shape KxHxW that represents the logits of
+              each class for each pixel.
         """
         images = [x["image"].to(self.device) for x in batched_inputs]
         images = [(x - self.pixel_mean) / self.pixel_std for x in images]
@@ -153,7 +155,7 @@ def forward(self, features, targets=None):
         """
         Returns:
             In training, returns (None, dict of losses)
-            In inference, returns (predictions, {})
+            In inference, returns (CxHxW logits, {})
         """
         x = self.layers(features)
         if self.training:

detectron2/structures/boxes.py

@@ -25,10 +25,12 @@ class BoxMode(IntEnum):
     """
     XYXY_REL = 2
     """
+    Not yet supported!
     (x0, y0, x1, y1) in range [0, 1]. They are relative to the size of the image.
     """
     XYWH_REL = 3
     """
+    Not yet supported!
     (x0, y0, w, h) in range [0, 1]. They are relative to the size of the image.
     """
     XYWHA_ABS = 4

detectron2/utils/visualizer.py

@@ -383,6 +383,7 @@ def draw_sem_seg(self, sem_seg, area_threshold=None, alpha=0.8):
 
         Args:
             sem_seg (Tensor or ndarray): the segmentation of shape (H, W).
+                Each value is the integer label of the pixel.
             area_threshold (int): segments with less than `area_threshold` are not drawn.
             alpha (float): the larger it is, the more opaque the segmentations are.
 

dev/packaging/gen_wheel_index.sh

@@ -11,7 +11,7 @@ fi
 index=$root/index.html
 
 cd "$root"
-for cu in cpu cu92 cu100 cu101; do
+for cu in cpu cu92 cu100 cu101 cu102; do
   cd $cu
   echo "Creating $PWD/index.html ..."
   for whl in *.whl; do

docs/tutorials/configs.md

@@ -1,19 +1,27 @@
-# Use Configs
+# Configs
 
-Detectron2's config system uses yaml and [yacs](https://github.com/rbgirshick/yacs).
-In addition to the basic operations that access and update a config, we provide
-the following extra functionalities:
+Detectron2 provides a key-value based config system that can be
+used to obtain standard, common behaviors.
+
+Detectron2's config system uses YAML and [yacs](https://github.com/rbgirshick/yacs).
+In addition to the [basic operations](../modules/config.html#detectron2.config.CfgNode)
+that access and update a config, we provide the following extra functionalities:
 
 1. The config can have `_BASE_: base.yaml` field, which will load a base config first.
    Values in the base config will be overwritten in sub-configs, if there are any conflicts.
    We provided several base configs for standard model architectures.
 2. We provide config versioning, for backward compatibility.
    If your config file is versioned with a config line like `VERSION: 2`,
-   detectron2 will still recognize it even if we rename some keys in the future.
+   detectron2 will still recognize it even if we change some keys in the future.
+
+"Config" is a very limited abstraction.
+We do not expect all features in detectron2 to be available through configs.
+If you need something that's not available in the config space,
+please write code using detectron2's API.
 
-### Use Configs
+### Basic Usage
 
-Some basic usage of the `CfgNode` object is shown below:
+Some basic usage of the `CfgNode` object is shown here. See more in [documentation](../modules/config.html#detectron2.config.CfgNode).
 ```python
 from detectron2.config import get_cfg
 cfg = get_cfg()    # obtain detectron2's default config
@@ -24,7 +32,16 @@ cfg.merge_from_list(["MODEL.WEIGHTS", "weights.pth"])   # can also load values f
 print(cfg.dump())  # print formatted configs
 ```
 
-To see a list of available configs in detectron2, see [Config References](../modules/config.html#config-references)
+Many builtin tools in detectron2 accepts command line config overwrite:
+Key-value pairs provided in the command line will overwrite the existing values in the config file.
+For example, [demo.py](../../demo/demo.py) can be used with
+```
+./demo.py --config-file config.yaml [--other-options] \
+  --opts MODEL.WEIGHTS /path/to/weights INPUT.MIN_SIZE_TEST 1000
+```
+
+To see a list of available configs in detectron2 and what they mean,
+check [Config References](../modules/config.html#config-references)
 
 
 ### Best Practice with Configs
@@ -39,7 +56,3 @@ To see a list of available configs in detectron2, see [Config References](../mod
 	 We print a warning when reading a config without version number.
    The official configs do not include version number because they are meant to
    be always up-to-date.
-
-4. Save a full config together with a trained model, and use it to run inference.
-   This is more robust to changes that may happen to the config definition
-   (e.g., if a default value changed), although we will try to avoid such changes.