[docs] Add loss convention (open-mmlab#3818)

* [docs] Add loss convention

* add example

* fixed backticks

* reduce code

* fixed lint

docs/conventions.md

@@ -0,0 +1,28 @@
+# Conventions
+
+Please check the following conventions if you would like to modify MMDetection as your own project.
+
+## Loss
+In MMDetection, a `dict` containing losses and metrics will be returned by `model(**data)`.
+
+For example, in bbox head,
+```python
+class BBoxHead(nn.Module):
+    ...
+    def loss(self, ...):
+        losses = dict()
+        # classification loss
+        losses['loss_cls'] = self.loss_cls(...)
+        # classification accuracy
+        losses['acc'] = accuracy(...)
+        # bbox regression loss
+        losses['loss_bbox'] = self.loss_bbox(...)
+        return losses
+```
+`bbox_head.loss()` will be called during model forward.
+The returned dict contains `'loss_bbox'`, `'loss_cls'`, `'acc'` .
+Only `'loss_bbox'`, `'loss_cls'` will be used during back propagation,
+`'acc'` will only be used as a metric to monitor training process.
+
+By default, only values whose keys contain `'loss'` will be back propagated.
+This behavior could be changed by modifying `BaseDetector.train_step()`.

docs/faq.md

@@ -14,7 +14,7 @@ We list some common troubles faced by many users and their corresponding solutio
 ## PyTorch/CUDA Environment
 
 - "RTX 30 series card fails when building MMCV or MMDet"
-    
+
     1. Temporary work-around: do `MMCV_WITH_OPS=1 MMCV_CUDA_ARGS='-gencode=arch=compute_80,code=sm_80' pip install -e .`.
     The common issue is `nvcc fatal : Unsupported gpu architecture 'compute_86'`. This means that the compiler should optimize for sm_86, i.e., nvidia 30 series card, but such optimizations have not been supported by CUDA toolkit 11.0.
     This work-around modifies the compile flag by adding `MMCV_CUDA_ARGS='-gencode=arch=compute_80,code=sm_80'`, which tells `nvcc` to optimize for **sm_80**, i.e., Nvidia A100. Although A100 is different from the 30 series card, they use similar ampere architecture. This may hurt the performance but it works.

docs/index.rst

@@ -32,6 +32,7 @@ Welcome to MMDetection's documentation!
    :maxdepth: 2
    :caption: Notes
 
+   conventions.md
    compatibility.md
    projects.md
    changelog.md