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

* 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

Author: NicolasHug

docs/source/beta_status.py

@@ -0,0 +1,20 @@
+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.models as M
 from tabulate import tabulate
 
+sys.path.append(os.path.abspath("."))
 
 # -- General configuration ------------------------------------------------
 
@@ -50,6 +52,7 @@
     "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
 --------------