From 6116812d51c6e5524ef48f8b14c0293ed674ed55 Mon Sep 17 00:00:00 2001 From: Nicolas Hug Date: Fri, 29 Jan 2021 08:21:57 -0500 Subject: [PATCH] Document undocumented parameters (#3299) * Document undodcumented parameters * remove setup.cfg changes * Properly pass normalize down instead of deprecating it * Fix flake8 * Add new CI check * Fix type spec * Leave normalize be part of kwargs Co-authored-by: Vasilis Vryniotis --- .circleci/config.yml | 12 ++++++++++++ .circleci/config.yml.in | 12 ++++++++++++ references/detection/coco_eval.py | 1 + setup.cfg | 3 +++ torchvision/datasets/video_utils.py | 1 + torchvision/models/detection/_utils.py | 1 + torchvision/models/detection/backbone_utils.py | 9 ++++++++- torchvision/models/quantization/googlenet.py | 1 + torchvision/models/quantization/inception.py | 1 + torchvision/models/quantization/resnet.py | 3 +++ torchvision/models/quantization/shufflenetv2.py | 4 ++++ torchvision/models/segmentation/segmentation.py | 4 ++-- torchvision/utils.py | 2 +- 13 files changed, 50 insertions(+), 4 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index d7d8409fe98..285bb65aebf 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -120,6 +120,16 @@ jobs: pip install --user --progress-bar off --editable . mypy --config-file mypy.ini + docstring_parameters_sync: + docker: + - image: circleci/python:3.7 + steps: + - checkout + - run: + command: | + pip install --user pydocstyle + pydocstyle + clang_format: docker: - image: circleci/python:3.7 @@ -1167,6 +1177,7 @@ workflows: - build_docs - python_lint - python_type_check + - docstring_parameters_sync - clang_format - torchhub_test - torch_onnx_test @@ -1283,6 +1294,7 @@ workflows: - circleci_consistency - python_lint - python_type_check + - docstring_parameters_sync - clang_format - torchhub_test - torch_onnx_test diff --git a/.circleci/config.yml.in b/.circleci/config.yml.in index 400ed7a0747..25733dd7b3a 100644 --- a/.circleci/config.yml.in +++ b/.circleci/config.yml.in @@ -120,6 +120,16 @@ jobs: pip install --user --progress-bar off --editable . mypy --config-file mypy.ini + docstring_parameters_sync: + docker: + - image: circleci/python:3.7 + steps: + - checkout + - run: + command: | + pip install --user pydocstyle + pydocstyle + clang_format: docker: - image: circleci/python:3.7 @@ -778,6 +788,7 @@ workflows: {{ build_workflows(windows_latest_only=True) }} - python_lint - python_type_check + - docstring_parameters_sync - clang_format - torchhub_test - torch_onnx_test @@ -796,6 +807,7 @@ workflows: - circleci_consistency - python_lint - python_type_check + - docstring_parameters_sync - clang_format - torchhub_test - torch_onnx_test diff --git a/references/detection/coco_eval.py b/references/detection/coco_eval.py index 814128b0364..09648f29ae4 100644 --- a/references/detection/coco_eval.py +++ b/references/detection/coco_eval.py @@ -239,6 +239,7 @@ def loadRes(self, resFile): """ Load result file and return a result api object. Args: + self (obj): coco object with ground truth annotations resFile (str): file name of result file Returns: res (obj): result api object diff --git a/setup.cfg b/setup.cfg index 19f6d24056a..fd3b74c47de 100644 --- a/setup.cfg +++ b/setup.cfg @@ -11,3 +11,6 @@ max-line-length = 120 max-line-length = 120 ignore = F401,E402,F403,W503,W504,F821 exclude = venv + +[pydocstyle] +select = D417 # Missing argument descriptions in the docstring diff --git a/torchvision/datasets/video_utils.py b/torchvision/datasets/video_utils.py index 0a7fbe94928..987270c4cd4 100644 --- a/torchvision/datasets/video_utils.py +++ b/torchvision/datasets/video_utils.py @@ -229,6 +229,7 @@ def compute_clips(self, num_frames, step, frame_rate=None): Args: num_frames (int): number of frames for the clip step (int): distance between two clips + frame_rate (int, optional): The frame rate """ self.num_frames = num_frames self.step = step diff --git a/torchvision/models/detection/_utils.py b/torchvision/models/detection/_utils.py index a3299bcf301..db9711760dc 100644 --- a/torchvision/models/detection/_utils.py +++ b/torchvision/models/detection/_utils.py @@ -86,6 +86,7 @@ def encode_boxes(reference_boxes, proposals, weights): Args: reference_boxes (Tensor): reference boxes proposals (Tensor): boxes to be encoded + weights (Tensor[4]): the weights for ``(x, y, w, h)`` """ # perform some unpacking to make it JIT-fusion friendly diff --git a/torchvision/models/detection/backbone_utils.py b/torchvision/models/detection/backbone_utils.py index 45f311d160c..4781c912d52 100644 --- a/torchvision/models/detection/backbone_utils.py +++ b/torchvision/models/detection/backbone_utils.py @@ -76,11 +76,18 @@ def resnet_fpn_backbone( Args: backbone_name (string): resnet architecture. Possible values are 'ResNet', 'resnet18', 'resnet34', 'resnet50', 'resnet101', 'resnet152', 'resnext50_32x4d', 'resnext101_32x8d', 'wide_resnet50_2', 'wide_resnet101_2' + pretrained (bool): If True, returns a model with backbone pre-trained on Imagenet norm_layer (torchvision.ops): it is recommended to use the default value. For details visit: (https://github.com/facebookresearch/maskrcnn-benchmark/issues/267) - pretrained (bool): If True, returns a model with backbone pre-trained on Imagenet trainable_layers (int): number of trainable (not frozen) resnet layers starting from final block. Valid values are between 0 and 5, with 5 meaning all backbone layers are trainable. + returned_layers (list of int): The layers of the network to return. Each entry must be in ``[1, 4]``. + By default all layers are returned. + extra_blocks (ExtraFPNBlock or None): if provided, extra operations will + be performed. It is expected to take the fpn features, the original + features and the names of the original features as input, and returns + a new list of feature maps and their corresponding names. By + default a ``LastLevelMaxPool`` is used. """ backbone = resnet.__dict__[backbone_name]( pretrained=pretrained, diff --git a/torchvision/models/quantization/googlenet.py b/torchvision/models/quantization/googlenet.py index 54ee6db0eae..3a74ccd542c 100644 --- a/torchvision/models/quantization/googlenet.py +++ b/torchvision/models/quantization/googlenet.py @@ -29,6 +29,7 @@ def googlenet(pretrained=False, progress=True, quantize=False, **kwargs): Args: pretrained (bool): If True, returns a model pre-trained on ImageNet progress (bool): If True, displays a progress bar of the download to stderr + quantize (bool): If True, return a quantized version of the model aux_logits (bool): If True, adds two auxiliary branches that can improve training. Default: *False* when pretrained is True otherwise *True* transform_input (bool): If True, preprocesses the input according to the method with which it diff --git a/torchvision/models/quantization/inception.py b/torchvision/models/quantization/inception.py index ae588e38256..efce265271f 100644 --- a/torchvision/models/quantization/inception.py +++ b/torchvision/models/quantization/inception.py @@ -38,6 +38,7 @@ def inception_v3(pretrained=False, progress=True, quantize=False, **kwargs): Args: pretrained (bool): If True, returns a model pre-trained on ImageNet progress (bool): If True, displays a progress bar of the download to stderr + quantize (bool): If True, return a quantized version of the model aux_logits (bool): If True, add an auxiliary branch that can improve training. Default: *True* transform_input (bool): If True, preprocesses the input according to the method with which it diff --git a/torchvision/models/quantization/resnet.py b/torchvision/models/quantization/resnet.py index 5fd3c039299..c6a87c8c7d9 100644 --- a/torchvision/models/quantization/resnet.py +++ b/torchvision/models/quantization/resnet.py @@ -143,6 +143,7 @@ def resnet18(pretrained=False, progress=True, quantize=False, **kwargs): Args: pretrained (bool): If True, returns a model pre-trained on ImageNet progress (bool): If True, displays a progress bar of the download to stderr + quantize (bool): If True, return a quantized version of the model """ return _resnet('resnet18', QuantizableBasicBlock, [2, 2, 2, 2], pretrained, progress, quantize, **kwargs) @@ -155,6 +156,7 @@ def resnet50(pretrained=False, progress=True, quantize=False, **kwargs): Args: pretrained (bool): If True, returns a model pre-trained on ImageNet progress (bool): If True, displays a progress bar of the download to stderr + quantize (bool): If True, return a quantized version of the model """ return _resnet('resnet50', QuantizableBottleneck, [3, 4, 6, 3], pretrained, progress, quantize, **kwargs) @@ -167,6 +169,7 @@ def resnext101_32x8d(pretrained=False, progress=True, quantize=False, **kwargs): Args: pretrained (bool): If True, returns a model pre-trained on ImageNet progress (bool): If True, displays a progress bar of the download to stderr + quantize (bool): If True, return a quantized version of the model """ kwargs['groups'] = 32 kwargs['width_per_group'] = 8 diff --git a/torchvision/models/quantization/shufflenetv2.py b/torchvision/models/quantization/shufflenetv2.py index a2030ca5ece..3f779db3817 100644 --- a/torchvision/models/quantization/shufflenetv2.py +++ b/torchvision/models/quantization/shufflenetv2.py @@ -107,6 +107,7 @@ def shufflenet_v2_x0_5(pretrained=False, progress=True, quantize=False, **kwargs Args: pretrained (bool): If True, returns a model pre-trained on ImageNet progress (bool): If True, displays a progress bar of the download to stderr + quantize (bool): If True, return a quantized version of the model """ return _shufflenetv2('shufflenetv2_x0.5', pretrained, progress, quantize, [4, 8, 4], [24, 48, 96, 192, 1024], **kwargs) @@ -121,6 +122,7 @@ def shufflenet_v2_x1_0(pretrained=False, progress=True, quantize=False, **kwargs Args: pretrained (bool): If True, returns a model pre-trained on ImageNet progress (bool): If True, displays a progress bar of the download to stderr + quantize (bool): If True, return a quantized version of the model """ return _shufflenetv2('shufflenetv2_x1.0', pretrained, progress, quantize, [4, 8, 4], [24, 116, 232, 464, 1024], **kwargs) @@ -135,6 +137,7 @@ def shufflenet_v2_x1_5(pretrained=False, progress=True, quantize=False, **kwargs Args: pretrained (bool): If True, returns a model pre-trained on ImageNet progress (bool): If True, displays a progress bar of the download to stderr + quantize (bool): If True, return a quantized version of the model """ return _shufflenetv2('shufflenetv2_x1.5', pretrained, progress, quantize, [4, 8, 4], [24, 176, 352, 704, 1024], **kwargs) @@ -149,6 +152,7 @@ def shufflenet_v2_x2_0(pretrained=False, progress=True, quantize=False, **kwargs Args: pretrained (bool): If True, returns a model pre-trained on ImageNet progress (bool): If True, displays a progress bar of the download to stderr + quantize (bool): If True, return a quantized version of the model """ return _shufflenetv2('shufflenetv2_x2.0', pretrained, progress, quantize, [4, 8, 4], [24, 244, 488, 976, 2048], **kwargs) diff --git a/torchvision/models/segmentation/segmentation.py b/torchvision/models/segmentation/segmentation.py index 371be9b97da..9ccc1d2ab44 100644 --- a/torchvision/models/segmentation/segmentation.py +++ b/torchvision/models/segmentation/segmentation.py @@ -152,8 +152,8 @@ def deeplabv3_resnet101(pretrained=False, progress=True, pretrained (bool): If True, returns a model pre-trained on COCO train2017 which contains the same classes as Pascal VOC progress (bool): If True, displays a progress bar of the download to stderr - num_classes (int): number of output classes of the model (including the background) - aux_loss (bool): If True, it uses an auxiliary loss + num_classes (int): The number of classes + aux_loss (bool): If True, include an auxiliary classifier """ return _load_model('deeplabv3', 'resnet101', pretrained, progress, num_classes, aux_loss, **kwargs) diff --git a/torchvision/utils.py b/torchvision/utils.py index 5043879e299..6290809a7d6 100644 --- a/torchvision/utils.py +++ b/torchvision/utils.py @@ -153,7 +153,7 @@ def draw_bounding_boxes( Args: image (Tensor): Tensor of shape (C x H x W) - bboxes (Tensor): Tensor of size (N, 4) containing bounding boxes in (xmin, ymin, xmax, ymax) format. Note that + boxes (Tensor): Tensor of size (N, 4) containing bounding boxes in (xmin, ymin, xmax, ymax) format. Note that the boxes are absolute coordinates with respect to the image. In other words: `0 <= xmin < xmax < W` and `0 <= ymin < ymax < H`. labels (List[str]): List containing the labels of bounding boxes.