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

[NicolasHug]

This PR adds a new .. betastatus :: <api_name> directive to show a warning in the docs for API surfaces that are still Beta. It can be used on entire classes, function, or specific parameter.

It renders like a normal .. warning:: (this can be changed):

@mthrok Following up on our internal discussion Would you mind sharing your thoughts on this? It'd be great if we could align regarding the documentation of Beta APIs. We don't need to agree on the underlying implementation, but letting users know about this in the docs is what matters. Thanks!

[NicolasHug]

Converting to draft to avoid merging before @mthrok can give his thoughts, but this is good to review and stable on my side.

[datumbox]

@NicolasHug Nice, I think that can handle both whole methods and specific parameters.

@fmassa I wonder if you have a list of APIs that are currently on beta or you could provide a few references, so that we can document the entire TorchVision.

[mthrok]

I think keeping the status value as argument is more flexible, such as ..api_status:: [beta, stable, prototype].
With the current approach, stable API can be only recognized by the lack of the directive.
I think this is error prune, considering the possibility where one adds a new feature but forgets to add the badge that says beta. Forgetting to add the directive automatically promotes the API to stable on the doc.

This would also allow to communicate the context of status change after moving it out of beta like This API has been promoted to stable in release "<>"..

[NicolasHug]

Thanks for your input @mthrok .

I originally had it like you mentioned ..api_status:: [beta, stable, prototype], but decided against it because:

• we don't actually document prototype stuff, although this might change
• A reasonable assumption is that if something isn't beta, then it's stable.

I don't feel strongly about this though. I'm open to using something like this, but then I'd like your thoughts on the following points:

• does that mean we would write api_status:: stable on all existing stable classes / functions ? If we say that a function is stable but one of its parameter is Beta (like the decode_jpeg() above), could this be potentially confusing?
• What should be the rendering of .. api_status:: stable ? Should be it like a .. note:: ? Or a badge? Something else?

This would also allow to communicate the context of status change after moving it out of beta like This API has been promoted to stable in release "<>"..

I agree this is good to document. Typically this could be done via the builtin .. versionchanged:: directive (but I don't remember if it renders properly with our theme).

[datumbox]

+1 on @mthrok's idea to include information on the docs about when a specific API became available.

Concerning marking everything versus marking only beta features, I agree with @NicolasHug that marking every module, class, method (or parameter) with a "stable" badge can be noisy. I think @mthrok does have a point about the fact that explicitly marking something is less error prone but I'm not sure what would be the policy to avoid putting badges all over the place. No strong opinions from me either, I think it's always OK to test something and get the input from the community rather than wait for the perfect solution. What's next to unblock this work?

[NicolasHug]

As discussed offline with @mthrok there's no blocker on his side. Let's move forward with this solution, we can of course revisit at any point in time regarding the underlying implementation.

I added the directive to all detection model builders and individual doc pages as well. I'll check with @fmassa later today if we missed anything, but this is good to go on my side.
EDIT: also added semantic segmentation and video models

[datumbox]

LGTM, thanks!