update docs

Summary: Pull Request resolved: fairinternal/detectron2#351

Differential Revision: D19215444

Pulled By: ppwwyyxx

fbshipit-source-id: f4d9f0376e24be57fdf9ae31886b911b314c4e6d

.github/CONTRIBUTING.md

@@ -34,10 +34,11 @@ When sending a PR, please do:
 
 1. Fork the repo and create your branch from `master`.
 2. If you've added code that should be tested, add tests.
-3. If you've changed APIs, update the documentation.
+3. If APIs are changed, update the documentation.
 4. Ensure the test suite passes.
 5. Make sure your code lints with `./dev/linter.sh`.
-6. If you haven't already, complete the Contributor License Agreement ("CLA").
+6. If a PR contains multiple orthogonal changes, split it to several PRs.
+7. If you haven't already, complete the Contributor License Agreement ("CLA").
 
 ## Contributor License Agreement ("CLA")
 In order to accept your pull request, we need you to submit a CLA. You only need

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

@@ -17,5 +17,5 @@ NOTE:
    please use the "Unexpected Problems / Bugs" issue template.
 
 2. 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, or what algorithm/methods can be
+	 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

@@ -34,6 +34,5 @@ Only in one of the two conditions we will help with it:
 
 ## Environment
 
-Please paste the output of `python -m detectron2.utils.collect_env`,
-or use `python detectron2/utils/collect_env.py`
-if detectron2 hasn't been successfully installed.
+Please paste the output of `python -m detectron2.utils.collect_env`.
+If detectron2 hasn't been successfully installed, use `python detectron2/utils/collect_env.py`.

INSTALL.md

@@ -23,15 +23,15 @@ After having the above dependencies, run:
 ```
 git clone https://github.com/facebookresearch/detectron2.git
 cd detectron2
-python setup.py build develop
+pip install -e .
 
 # or if you are on macOS
-# MACOSX_DEPLOYMENT_TARGET=10.9 CC=clang CXX=clang++ python setup.py build develop
+# MACOSX_DEPLOYMENT_TARGET=10.9 CC=clang CXX=clang++ pip install -e .
 
-# or, as an alternative to `setup.py`, do
-# pip install [--editable] .
+# or, as an alternative to `pip install`, use
+# python setup.py build develop
 ```
-Note: you may need to rebuild detectron2 after reinstalling a different build of PyTorch.
+Note: you often need to rebuild detectron2 after reinstalling PyTorch.
 
 ### Common Installation Issues
 
@@ -47,20 +47,20 @@ Note: you may need to rebuild detectron2 after reinstalling a different build of
 
 	* detectron2 or torchvision is not compiled using gcc >= 4.9.
 
-	  You'll see a warning message during compilation in this case. Please remove the files you build,
-		and rebuild them.
+	  You'll see a warning message during compilation in this case. Please remove the files you built,
+		and rebuild them with a supported compiler.
 		Technically, you need the identical compiler that's used to build pytorch to guarantee
 		compatibility. But in practice, gcc >= 4.9 should work OK.
 
 + Undefined C++ symbols in `detectron2/_C*.so`:
 
-  * This can happen with old anaconda. Try `conda update libgcc`.
+  * This can happen with old anaconda. Try `conda update libgcc`. Then remove the files you built and rebuild them.
 
-+ Undefined cuda symbols. The version of NVCC you use to build detectron2 or torchvision does
-	not match the version of cuda you are running with.
-	This often happens when using anaconda's cuda runtime.
++ Undefined CUDA symbols. The version of NVCC you use to build detectron2 or torchvision does
+	not match the version of CUDA you are running with.
+	This often happens when using anaconda's CUDA runtime.
 
-+ "Not compiled with GPU support": make sure
++ "Not compiled with GPU support" or "Detectron2 CUDA Compiler: not available": make sure
 	```
 	python -c 'import torch; from torch.utils.cpp_extension import CUDA_HOME; print(torch.cuda.is_available(), CUDA_HOME)'
 	```
@@ -70,4 +70,8 @@ Note: you may need to rebuild detectron2 after reinstalling a different build of
   * You build detectron2 with one version of CUDA but run it with a different version.
   * Detectron2 is not built with the correct compute compability for the GPU model.
     The compute compability defaults to match the GPU found on the machine during building,
-    and can be controlled by `TORCH_CUDA_ARCH_LIST` environment variable during installation.
+    and can be controlled by `TORCH_CUDA_ARCH_LIST` environment variable during building.
+
+  You can use `python -m detectron2.utils.collect_env` to find out inconsistent CUDA versions.
+	In its output, you should expect "Detectron2 CUDA Compiler", "CUDA_HOME", "PyTorch built with - CUDA"
+	to contain cuda libraries of the same version.

MODEL_ZOO.md

@@ -21,6 +21,7 @@ Unless otherwise noted, the following settings are used for all runs:
   for speed comparison.
 * Inference speed is measured by `tools/train_net.py --eval-only`, or [inference_on_dataset()](https://detectron2.readthedocs.io/modules/evaluation.html#detectron2.evaluation.inference_on_dataset),
   with batch size 1 in detectron2 directly.
+	Measuring it with your own code will likely introduce other overhead.
   The actual deployment should in general be faster than the given inference
   speed due to more optimizations.
 * Training speed is averaged across the entire training.

detectron2/data/build.py

@@ -322,8 +322,8 @@ def build_detection_train_loader(cfg, mapper=None):
         batch_sampler = torch.utils.data.sampler.BatchSampler(
             sampler, images_per_worker, drop_last=True
         )
-        collate_fn = trivial_batch_collator
         # drop_last so the batch always have the same size
+        collate_fn = trivial_batch_collator
 
     data_loader = torch.utils.data.DataLoader(
         dataset,

detectron2/modeling/roi_heads/keypoint_head.py

@@ -97,7 +97,7 @@ def keypoint_rcnn_inference(pred_keypoint_logits, pred_instances):
         pred_instances (list[Instances]): A list of N Instances, where N is the number of images.
 
     Returns:
-        None. boxes will contain an extra "pred_keypoints" field.
+        None. Each element in pred_instances will contain an extra "pred_keypoints" field.
             The field is a tensor of shape (#instance, K, 3) where the last
             dimension corresponds to (x, y, score).
             The scores are larger than 0.

detectron2/utils/events.py

@@ -13,6 +13,11 @@
 
 
 def get_event_storage():
+    """
+    Returns:
+        The :class:`EventStorage` object that's currently being used.
+        Throws an error if no :class`EventStorage` is currently enabled.
+    """
     assert len(
         _CURRENT_STORAGE_STACK
     ), "get_event_storage() has to be called inside a 'with EventStorage(...)' context!"

dev/README.md

@@ -3,4 +3,5 @@
 
 - `linter.sh`: lint the codebase before commit
 - `run_{inference,instant}_tests.sh`: run inference/training for a few iterations.
-- `parse_results.sh`: parse results from log file.
+   Note that these tests require 2 GPUs.
+- `parse_results.sh`: parse results from a log file.

docker/Dockerfile

@@ -26,6 +26,8 @@ RUN pip install --user 'git+https://github.com/facebookresearch/fvcore'
 # install detectron2
 RUN git clone https://github.com/facebookresearch/detectron2 detectron2_repo
 ENV FORCE_CUDA="1"
+# This will build detectron2 for all common cuda architectures and take a lot more time,
+# because inside `docker build`, there is no way to tell which architecture will be used.
 ENV TORCH_CUDA_ARCH_LIST="Kepler;Kepler+Tesla;Maxwell;Maxwell+Tegra;Pascal;Volta;Turing"
 RUN pip install --user -e detectron2_repo
 

docs/tutorials/training.md

@@ -16,3 +16,20 @@ You can use
 which does single-cost single-optimizer single-data-source training.
 Or use [DefaultTrainer().train()](../modules/engine.html#detectron2.engine.defaults.DefaultTrainer)
 which includes more standard behavior that one might want to opt in.
+This also means that it's less likely to support some non-standard behavior
+you might want during research.
+
+
+### Logging of Metrics
+
+During training, metrics are logged with a centralized [EventStorage](../modules/utils.html#detectron2.utils.events.EventStorage).
+You can use the following code to access it and log metrics to it:
+```
+from detectron2.utils.events import get_event_storage
+
+# inside the training:
+storage = get_event_storage()
+storage.put_scalar("some_accuracy", value)
+```
+
+Refer to its documentation for more details.