Add new `.. betastatus::` directive and document Beta APIs (#6115)

* Add new .. betastatus:: directive to document Beta APIs

* Also add it for the fine-grained video API

* Add directive for all builders and pages of Detection module

* Also segmentation and video models

docs/source/beta_status.py

+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+
+class BetaStatus(Directive):
+    has_content = True
+
+    def run(self):
+        api_name = " ".join(self.content)
+        text = f"The {api_name} is in Beta stage, and backward compatibility is not guaranteed."
+        return [nodes.warning("", nodes.paragraph("", "", nodes.Text(text)))]
+
+
+def setup(app):
+    app.add_directive("betastatus", BetaStatus)
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/source/conf.py

@@ -21,6 +21,7 @@
 # sys.path.insert(0, os.path.abspath('.'))
 
 import os
+import sys
 import textwrap
 from copy import copy
 from pathlib import Path
@@ -30,6 +31,7 @@ import torchvision
 import torchvision.models as M
 from tabulate import tabulate
 
+sys.path.append(os.path.abspath("."))
 
 # -- General configuration ------------------------------------------------
 
@@ -50,6 +52,7 @@ extensions = [
     "sphinx.ext.duration",
     "sphinx_gallery.gen_gallery",
     "sphinx_copybutton",
+    "beta_status",
 ]
 
 sphinx_gallery_conf = {

docs/source/io.rst

@@ -26,6 +26,8 @@ In addition to the :mod:`read_video` function, we provide a high-performance
 lower-level API for more fine-grained control compared to the :mod:`read_video` function.
 It does all this whilst fully supporting torchscript.
 
+.. betastatus:: fine-grained video API
+
 .. autosummary::
     :toctree: generated/
     :template: class.rst

docs/source/models.rst

@@ -272,6 +272,8 @@ Semantic Segmentation
 
 .. currentmodule:: torchvision.models.segmentation
 
+.. betastatus:: segmentation module
+
 The following semantic segmentation models are available, with or without
 pre-trained weights:
 
@@ -334,6 +336,8 @@ keypoint detection are initialized with the classification models
 in torchvision. The models expect a list of ``Tensor[C, H, W]``.
 Check the constructor of the models for more information.
 
+.. betastatus:: detection module
+
 Object Detection
 ----------------
 
@@ -453,6 +457,8 @@ Video Classification
 
 .. currentmodule:: torchvision.models.video
 
+.. betastatus:: video module
+
 The following video classification models are available, with or without
 pre-trained weights:
 

docs/source/models/deeplabv3.rst

@@ -6,6 +6,8 @@ DeepLabV3
 The DeepLabV3 model is based on the `Rethinking Atrous Convolution for Semantic
 Image Segmentation <https://arxiv.org/abs/1706.05587>`__ paper.
 
+.. betastatus:: segmentation module
+
 
 Model builders
 --------------

docs/source/models/faster_rcnn.rst

@@ -3,10 +3,12 @@ Faster R-CNN
 
 .. currentmodule:: torchvision.models.detection
 
+
 The Faster R-CNN model is based on the `Faster R-CNN: Towards Real-Time Object Detection 
 with Region Proposal Networks <https://arxiv.org/abs/1506.01497>`__
 paper.
 
+.. betastatus:: detection module
 
 Model builders
 --------------

docs/source/models/fcn.rst

@@ -7,6 +7,8 @@ The FCN model is based on the `Fully Convolutional Networks for Semantic
 Segmentation <https://arxiv.org/abs/1411.4038>`__
 paper.
 
+.. betastatus:: segmentation module
+
 
 Model builders
 --------------

docs/source/models/fcos.rst

@@ -6,6 +6,8 @@ FCOS
 The RetinaNet model is based on the `FCOS: Fully Convolutional One-Stage Object Detection
 <https://arxiv.org/abs/1904.01355>`__ paper.
 
+.. betastatus:: detection module
+
 Model builders
 --------------
 

docs/source/models/keypoint_rcnn.rst

@@ -6,6 +6,8 @@ Keypoint R-CNN
 The Keypoint R-CNN model is based on the `Mask R-CNN
 <https://arxiv.org/abs/1703.06870>`__ paper.
 
+.. betastatus:: detection module
+
 
 Model builders
 --------------

docs/source/models/lraspp.rst

@@ -5,6 +5,8 @@ LRASPP
 
 The LRASPP model is based on the `Searching for MobileNetV3 <https://arxiv.org/abs/1905.02244>`_ paper.
 
+.. betastatus:: segmentation module
+
 Model builders
 --------------
 

docs/source/models/mask_rcnn.rst

@@ -6,6 +6,8 @@ Mask R-CNN
 The Mask R-CNN model is based on the `Mask R-CNN <https://arxiv.org/abs/1703.06870>`__
 paper.
 
+.. betastatus:: detection module
+
 
 Model builders
 --------------

docs/source/models/retinanet.rst

@@ -6,6 +6,8 @@ RetinaNet
 The RetinaNet model is based on the `Focal Loss for Dense Object Detection
 <https://arxiv.org/abs/1708.02002>`__ paper.
 
+.. betastatus:: detection module
+
 Model builders
 --------------
 

docs/source/models/ssd.rst

@@ -6,6 +6,8 @@ SSD
 The SSD model is based on the `SSD: Single Shot MultiBox Detector
 <https://arxiv.org/abs/1512.02325>`__ paper.
 
+.. betastatus:: detection module
+
 
 Model builders
 --------------

docs/source/models/ssdlite.rst

@@ -8,6 +8,7 @@ The SSDLite model is based on the `SSD: Single Shot MultiBox Detector
 <https://arxiv.org/abs/1905.02244>`__ and `MobileNetV2: Inverted Residuals and Linear
 Bottlenecks <https://arxiv.org/abs/1801.04381>__` papers.
 
+.. betastatus:: detection module
 
 Model builders
 --------------

docs/source/models/video_resnet.rst

@@ -6,6 +6,8 @@ Video ResNet
 The VideoResNet model is based on the `A Closer Look at Spatiotemporal
 Convolutions for Action Recognition <https://arxiv.org/abs/1711.11248>`__ paper.
 
+.. betastatus:: video module
+
 
 Model builders
 --------------

torchvision/io/image.py

@@ -145,6 +145,8 @@ def decode_jpeg(
             with `nvjpeg <https://developer.nvidia.com/nvjpeg>`_. This is only
             supported for CUDA version >= 10.1
 
+            .. betastatus:: device parameter
+
             .. warning::
                 There is a memory leak in the nvjpeg library for CUDA versions < 11.6.
                 Make sure to rely on CUDA 11.6 or above before using ``device="cuda"``.

torchvision/io/video_reader.py

@@ -30,6 +30,8 @@ class VideoReader:
     Supports frame-by-frame reading of various streams from a single video
     container.
 
+    .. betastatus:: VideoReader class
+
     Example:
         The following examples creates a :mod:`VideoReader` object, seeks into 2s
         point, and returns a single frame::

torchvision/models/detection/faster_rcnn.py

@@ -469,6 +469,8 @@ def fasterrcnn_resnet50_fpn(
     Detection with Region Proposal Networks <https://arxiv.org/abs/1506.01497>`__
     paper.
 
+    .. betastatus:: detection module
+
     The input to the model is expected to be a list of tensors, each of shape ``[C, H, W]``, one for each
     image, and should be in ``0-1`` range. Different images can have different sizes.
 
@@ -580,6 +582,8 @@ def fasterrcnn_resnet50_fpn_v2(
     Constructs an improved Faster R-CNN model with a ResNet-50-FPN backbone from `Benchmarking Detection
     Transfer Learning with Vision Transformers <https://arxiv.org/abs/2111.11429>`__ paper.
 
+    .. betastatus:: detection module
+
     It works similarly to Faster R-CNN with ResNet-50 FPN backbone. See
     :func:`~torchvision.models.detection.fasterrcnn_resnet50_fpn` for more
     details.
@@ -697,6 +701,8 @@ def fasterrcnn_mobilenet_v3_large_320_fpn(
     """
     Low resolution Faster R-CNN model with a MobileNetV3-Large backbone tunned for mobile use cases.
 
+    .. betastatus:: detection module
+
     It works similarly to Faster R-CNN with ResNet-50 FPN backbone. See
     :func:`~torchvision.models.detection.fasterrcnn_resnet50_fpn` for more
     details.
@@ -767,6 +773,9 @@ def fasterrcnn_mobilenet_v3_large_fpn(
 ) -> FasterRCNN:
     """
     Constructs a high resolution Faster R-CNN model with a MobileNetV3-Large FPN backbone.
+
+    .. betastatus:: detection module
+
     It works similarly to Faster R-CNN with ResNet-50 FPN backbone. See
     :func:`~torchvision.models.detection.fasterrcnn_resnet50_fpn` for more
     details.

torchvision/models/detection/fcos.py

@@ -685,6 +685,8 @@ def fcos_resnet50_fpn(
     """
     Constructs a FCOS model with a ResNet-50-FPN backbone.
 
+    .. betastatus:: detection module
+
     Reference: `FCOS: Fully Convolutional One-Stage Object Detection <https://arxiv.org/abs/1904.01355>`_.
                `FCOS: A simple and strong anchor-free object detector <https://arxiv.org/abs/2006.09214>`_.
 

torchvision/models/detection/keypoint_rcnn.py

@@ -375,6 +375,8 @@ def keypointrcnn_resnet50_fpn(
     """
     Constructs a Keypoint R-CNN model with a ResNet-50-FPN backbone.
 
+    .. betastatus:: detection module
+
     Reference: `Mask R-CNN <https://arxiv.org/abs/1703.06870>`__.
 
     The input to the model is expected to be a list of tensors, each of shape ``[C, H, W]``, one for each