[docs] use versionadded, versionchanged and deprecated directive

[ydcjeff]

🚀 Feature

Use .. versionadded::, .. versionchanged:: and .. deprecated:: directive, so that user knows which features are added / changed / deprecated in which version and they can navigate the docs easily without changing the docs from version to version.

Ref: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded

I know PyTorch takes a lot of care for documentation, GitHub Release notes.
Most of use read github release notes, too.
But, for those who are not quite get in touch with github release notes, I think it's better to provide those directives so that even if we are in the latest docs, we can know which version to use if we just need a certain feature of pytorch (but, yes we normally use latest version, I think it might help a bit for production use cases.)

After all, this is a suggestion, let me know what pytorch devs think.
Thank you!

cc @jlin27 @mruberry

[ailzhang]

Given the amount of deprecated warnings we currently have, this sounds like a great improvement for user experience. Tagging triage review so that we can discuss the priority.

[ezyang]

We definitely should be using deprecated for deprecated features (if we aren't already). It may be difficult to make sure everything is up to date. We might be able to crowdsource historical annotations once we have one or two examples of how to do it.

[ydcjeff]

@ezyang Here's the example of output using

• .. versionadded:: - https://pytorch-issue-51197.netlify.app/generated/torch.nn.silu#torch.nn.SiLU
• .. versionchanged:: - https://pytorch-issue-51197.netlify.app/generated/torch.nn.hardsigmoid#torch.nn.Hardsigmoid
• .. deprecated:: - https://pytorch-issue-51197.netlify.app/generated/torch.norm.html#torch.norm

Code:

class SiLU(Module):
    r"""Applies the silu function, element-wise.
    ...

    .. versionadded:: 1.7.0  # added this one
    """

class Hardsigmoid(Module):
    r"""Applies the element-wise function:
    ...

    .. versionchanged:: 1.7.0
        Added ``inplace`` option.  # can write any normal RST description we want.
    """

def norm(input, p="fro", dim=None, keepdim=False, out=None, dtype=None):  # noqa: 749
    r"""Returns the matrix norm or vector norm of a given tensor.
    ...

    .. deprecated:: 1.7.0

        torch.norm is deprecated and may be removed in a future PyTorch release.
        Use :func:`torch.linalg.norm` instead, but note that :func:`torch.linalg.norm`
        has a different signature and slightly different behavior that is
        more consistent with NumPy's numpy.linalg.norm.
    """

[mthrok]

So, do we have a (sort of) agreement of (proactively) using these directives? I do not see a reason not to use them, but with a explicit consensus, domain libraries can start working on it.

[ezyang]

Yup, go for it.