update docs

Summary: Pull Request resolved: fairinternal/detectron2#525

Reviewed By: alexander-kirillov

Differential Revision: D27383548

Pulled By: ppwwyyxx

fbshipit-source-id: 71dbfcf6bc0500ce26257ce801fb11e98892e653

.flake8

@@ -9,4 +9,4 @@ max-complexity = 18
 select = B,C,E,F,W,T4,B9
 exclude = build
 per-file-ignores =
-  **/__init__.py:F401,F403
+  **/__init__.py:F401,F403,E402

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

@@ -39,7 +39,7 @@ Only in one of the two conditions we will help with it:
 
 Paste the output of the following command:
 ```
-wget -nc -q https://github.com/facebookresearch/detectron2/raw/master/detectron2/utils/collect_env.py && python collect_env.py
+wget -nc -nv 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,

INSTALL.md

@@ -239,6 +239,15 @@ whose version is closer to what's used by PyTorch (available in `torch.__config_
 </details>
 
 
+<details>
+<summary>
+"library not found for -lstdc++" on older version of MacOS
+</summary>
+<br/>
+See [this stackoverflow answer](https://stackoverflow.com/questions/56083725/macos-build-issues-lstdc-not-found-while-building-python-package).
+</details>
+
+
 ### Installation inside specific environments:
 
 * __Colab__: see our [Colab Tutorial](https://colab.research.google.com/drive/16jcaJoc6bCFAQ96jDe2HwtXj7BMD_-m5)

detectron2/config/__init__.py

@@ -11,3 +11,9 @@
     "upgrade_config",
     "configurable",
 ]
+
+
+from detectron2.utils.env import fixup_module_metadata
+
+fixup_module_metadata(__name__, globals(), __all__)
+del fixup_module_metadata

detectron2/data/build.py

@@ -369,9 +369,10 @@ def build_detection_train_loader(
         num_workers (int): number of parallel data loading workers
 
     Returns:
-        torch.utils.data.DataLoader: a dataloader. Each output from it is a
-            ``list[mapped_element]`` of length ``total_batch_size / num_workers``,
-            where ``mapped_element`` is produced by the ``mapper``.
+        torch.utils.data.DataLoader:
+            a dataloader. Each output from it is a ``list[mapped_element]`` of length
+            ``total_batch_size / num_workers``, where ``mapped_element`` is produced
+            by the ``mapper``.
     """
     if isinstance(dataset, list):
         dataset = DatasetFromList(dataset, copy=False)

detectron2/data/datasets/coco.py

@@ -353,6 +353,12 @@ def convert_to_coco_dict(dataset_name):
 
             # COCO requirement: XYWH box format for axis-align and XYWHA for rotated
             bbox = annotation["bbox"]
+            if isinstance(bbox, np.ndarray):
+                if bbox.ndim != 1:
+                    raise ValueError(f"bbox has to be 1-dimensional. Got shape={bbox.shape}.")
+                bbox = bbox.tolist()
+            if len(bbox) not in [4, 5]:
+                raise ValueError(f"bbox has to has length 4 or 5. Got {bbox}.")
             from_bbox_mode = annotation["bbox_mode"]
             to_bbox_mode = BoxMode.XYWH_ABS if len(bbox) == 4 else BoxMode.XYWHA_ABS
             bbox = BoxMode.convert(bbox, from_bbox_mode, to_bbox_mode)

detectron2/data/detection_utils.py

@@ -172,7 +172,8 @@ def read_image(file_name, format=None):
         format (str): one of the supported image modes in PIL, or "BGR" or "YUV-BT.601".
 
     Returns:
-        image (np.ndarray): an HWC image in the given format, which is 0-255, uint8 for
+        image (np.ndarray):
+            an HWC image in the given format, which is 0-255, uint8 for
             supported image modes in PIL or "BGR"; float (0-1 for Y) for YUV-BT.601.
     """
     with PathManager.open(file_name, "rb") as f:

detectron2/data/samplers/distributed_sampler.py

@@ -99,8 +99,8 @@ def repeat_factors_from_category_frequency(dataset_dicts, repeat_thresh):
                 repeated twice.
 
         Returns:
-            torch.Tensor: the i-th element is the repeat factor for the dataset image
-                at index i.
+            torch.Tensor:
+                the i-th element is the repeat factor for the dataset image at index i.
         """
         # 1. For each category c, compute the fraction of images that contain it: f(c)
         category_freq = defaultdict(int)

detectron2/data/transforms/__init__.py

@@ -6,3 +6,9 @@
 from .augmentation_impl import *
 
 __all__ = [k for k in globals().keys() if not k.startswith("_")]
+
+
+from detectron2.utils.env import fixup_module_metadata
+
+fixup_module_metadata(__name__, globals(), __all__)
+del fixup_module_metadata

detectron2/modeling/__init__.py

@@ -50,3 +50,9 @@
 
 _EXCLUDE = {"ShapeSpec"}
 __all__ = [k for k in globals().keys() if k not in _EXCLUDE and not k.startswith("_")]
+
+
+from detectron2.utils.env import fixup_module_metadata
+
+fixup_module_metadata(__name__, globals(), __all__)
+del fixup_module_metadata

detectron2/modeling/meta_arch/retinanet.py

@@ -15,7 +15,7 @@
 from detectron2.utils.events import get_event_storage
 
 from ..anchor_generator import build_anchor_generator
-from ..backbone import build_backbone
+from ..backbone import Backbone, build_backbone
 from ..box_regression import Box2BoxTransform, _dense_box_regression_loss
 from ..matcher import Matcher
 from ..postprocessing import detector_postprocess
@@ -49,8 +49,8 @@ class RetinaNet(nn.Module):
     def __init__(
         self,
         *,
-        backbone,
-        head,
+        backbone: Backbone,
+        head: nn.Module,
         head_in_features,
         anchor_generator,
         box2box_transform,
@@ -355,14 +355,13 @@ def label_anchors(self, anchors, gt_instances):
                 for the i-th input image.
 
         Returns:
-            list[Tensor]:
-                List of #img tensors. i-th element is a vector of labels whose length is
-                the total number of anchors across all feature maps (sum(Hi * Wi * A)).
-                Label values are in {-1, 0, ..., K}, with -1 means ignore, and K means background.
-            list[Tensor]:
-                i-th element is a Rx4 tensor, where R is the total number of anchors across
-                feature maps. The values are the matched gt boxes for each anchor.
-                Values are undefined for those anchors not labeled as foreground.
+            list[Tensor]: List of #img tensors. i-th element is a vector of labels whose length is
+            the total number of anchors across all feature maps (sum(Hi * Wi * A)).
+            Label values are in {-1, 0, ..., K}, with -1 means ignore, and K means background.
+
+            list[Tensor]: i-th element is a Rx4 tensor, where R is the total number of anchors
+            across feature maps. The values are the matched gt boxes for each anchor.
+            Values are undefined for those anchors not labeled as foreground.
         """
         anchors = Boxes.cat(anchors)  # Rx4
 

detectron2/modeling/roi_heads/roi_heads.py

@@ -759,7 +759,7 @@ def forward_with_given_boxes(
                 "pred_boxes" and "pred_classes" to exist.
 
         Returns:
-            instances (list[Instances]):
+            list[Instances]:
                 the same `Instances` objects, with extra
                 fields such as `pred_masks` or `pred_keypoints`.
         """

detectron2/structures/__init__.py

@@ -9,3 +9,9 @@
 from .rotated_boxes import pairwise_iou as pairwise_iou_rotated
 
 __all__ = [k for k in globals().keys() if not k.startswith("_")]
+
+
+from detectron2.utils.env import fixup_module_metadata
+
+fixup_module_metadata(__name__, globals(), __all__)
+del fixup_module_metadata

detectron2/utils/env.py

@@ -18,6 +18,12 @@
 """
 
 
+DOC_BUILDING = os.getenv("_DOC_BUILDING", False)  # set in docs/conf.py
+"""
+Whether we're building documentation.
+"""
+
+
 def seed_all_rng(seed=None):
     """
     Set the random seed for the RNG in torch, numpy and python.
@@ -124,3 +130,41 @@ def setup_custom_environment(custom_module):
         "required callable attribute 'setup_environment'."
     ).format(custom_module)
     module.setup_environment()
+
+
+def fixup_module_metadata(module_name, namespace, keys=None):
+    """
+    Fix the __qualname__ of module members to be their exported api name, so
+    when they are referenced in docs, sphinx can find them. Reference:
+    https://github.com/python-trio/trio/blob/6754c74eacfad9cc5c92d5c24727a2f3b620624e/trio/_util.py#L216-L241
+    """
+    if not DOC_BUILDING:
+        return
+    seen_ids = set()
+
+    def fix_one(qualname, name, obj):
+        # avoid infinite recursion (relevant when using
+        # typing.Generic, for example)
+        if id(obj) in seen_ids:
+            return
+        seen_ids.add(id(obj))
+
+        mod = getattr(obj, "__module__", None)
+        if mod is not None and (mod.startswith(module_name) or mod.startswith("fvcore.")):
+            obj.__module__ = module_name
+            # Modules, unlike everything else in Python, put fully-qualitied
+            # names into their __name__ attribute. We check for "." to avoid
+            # rewriting these.
+            if hasattr(obj, "__name__") and "." not in obj.__name__:
+                obj.__name__ = name
+                obj.__qualname__ = qualname
+            if isinstance(obj, type):
+                for attr_name, attr_value in obj.__dict__.items():
+                    fix_one(objname + "." + attr_name, attr_name, attr_value)
+
+    if keys is None:
+        keys = namespace.keys()
+    for objname in keys:
+        if not objname.startswith("_"):
+            obj = namespace[objname]
+            fix_one(objname, objname, obj)

docs/conf.py

@@ -61,7 +61,7 @@ def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode):
 from recommonmark.parser import CommonMarkParser
 
 sys.path.insert(0, os.path.abspath("../"))
-os.environ["DOC_BUILDING"] = "True"
+os.environ["_DOC_BUILDING"] = "True"
 DEPLOY = os.environ.get("READTHEDOCS") == "True"
 
 
@@ -78,11 +78,13 @@ def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode):
     ]:
         sys.modules[m] = mock.Mock(name=m)
     sys.modules['torch'].__version__ = "1.7"  # fake version
+    HAS_TORCH = False
 else:
     try:
         torch.ops.detectron2 = mock.Mock(name="torch.ops.detectron2")
     except:
         pass
+    HAS_TORCH = True
 
 for m in [
     "cv2", "scipy", "portalocker", "detectron2._C",
@@ -96,6 +98,12 @@ def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode):
 
 import detectron2  # isort: skip
 
+if HAS_TORCH:
+    from detectron2.utils.env import fixup_module_metadata
+
+    fixup_module_metadata("torch.nn", torch.nn.__dict__)
+    fixup_module_metadata("torch.utils.data", torch.utils.data.__dict__)
+
 
 project = "detectron2"
 copyright = "2019-2020, detectron2 contributors"
@@ -141,7 +149,7 @@ def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode):
     intersphinx_timeout = 10
 else:
     # skip this when building locally
-    intersphinx_timeout = 0.1
+    intersphinx_timeout = 0.5
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.6", None),
     "numpy": ("https://docs.scipy.org/doc/numpy/", None),
@@ -317,6 +325,10 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
         "1704.04861",
         "MobileNets: Efficient Convolutional Neural Networks for Mobile Vision Applications",
     ),
+    "deeplabv3+": (
+        "1802.02611",
+        "Encoder-Decoder with Atrous Separable Convolution for Semantic Image Segmentation",
+    ),
 }
 
 

docs/modules/data.rst

@@ -1,4 +1,4 @@
-detectron2.data 
+detectron2.data
 =======================
 
 .. autodata:: detectron2.data.DatasetCatalog(dict)
@@ -35,13 +35,3 @@ detectron2.data.samplers module
     :members:
     :undoc-members:
     :show-inheritance:
-
-
-detectron2.data.transforms module
----------------------------------------
-
-.. automodule:: detectron2.data.transforms
-    :members:
-    :undoc-members:
-    :show-inheritance:
-    :imported-members:

docs/notes/changelog.md

@@ -1,4 +1,4 @@
-# Backward Compatibility and Change Log
+# Change Log and Backward Compatibility
 
 ### Releases
 See release logs at
@@ -38,7 +38,7 @@ There is no need for an open source user to worry about this.
 * v1: Rename `RPN_HEAD.NAME` to `RPN.HEAD_NAME`.
 * v2: A batch of rename of many configurations before release.
 
-### Silent Regression in Historical Versions:
+### Silent Regressions in Historical Versions:
 
 We list a few silent regressions, since they may silently produce incorrect results and will be hard to debug.
 

docs/requirements.txt

@@ -3,7 +3,7 @@ numpy
 tqdm
 docutils==0.16
 # https://github.com/sphinx-doc/sphinx/commit/7acd3ada3f38076af7b2b5c9f3b60bb9c2587a3d
-git+git://github.com/sphinx-doc/sphinx.git@7acd3ada3f38076af7b2b5c9f3b60bb9c2587a3d
+sphinx==3.2.0
 recommonmark==0.6.0
 sphinx_rtd_theme
 matplotlib
@@ -13,8 +13,7 @@ tabulate
 cloudpickle
 Pillow
 future
-requests
-six
 git+git://github.com/facebookresearch/fvcore.git
 https://download.pytorch.org/whl/cpu/torch-1.7.0%2Bcpu-cp37-cp37m-linux_x86_64.whl
 https://download.pytorch.org/whl/cpu/torchvision-0.8.1%2Bcpu-cp37-cp37m-linux_x86_64.whl
+omegaconf

setup.py

@@ -221,6 +221,8 @@ def get_model_zoo_configs() -> List[str]:
         "pydot",  # used to save caffe2 SVGs
         "dataclasses; python_version<'3.7'",
         "omegaconf==2.1.0.dev22",
+        # When adding to the list, may need to update docs/requirements.txt
+        # or add mock in docs/conf.py
     ],
     extras_require={
         "all": [