DOC: fail to build if there are warnings (pytorch#41335)

Summary:
Merge after pytorchgh-41334 and pytorchgh-41321 (EDIT: both are merged).
Closes pytorchgh-38011

This is the last in a series of PRs to build documentation without warnings. It adds `-WT --keepgoing` to the shpinx build which will [fail the build if there are warnings](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-W), print a [trackeback on error](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-T) and [finish the build](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-keep-going) even when there are warnings.

It should fail now, but pass once the PRs mentioned at the top are merged.

Pull Request resolved: pytorch#41335

Reviewed By: pbelevich

Differential Revision: D22794425

Pulled By: mruberry

fbshipit-source-id: eb2903e50759d1d4f66346ee2ceebeecfac7b094

Author: mattip

.circleci/scripts/python_doc_push_script.sh

@@ -50,21 +50,13 @@ export PATH=/opt/conda/bin:$PATH
 
 rm -rf pytorch || true
 
-# Install TensorBoard in python 3 so torch.utils.tensorboard classes render
-pip install -q https://s3.amazonaws.com/ossci-linux/wheels/tensorboard-1.14.0a0-py3-none-any.whl
-
 # Get all the documentation sources, put them in one place
 pushd "$pt_checkout"
-checkout_install_torchvision
 pushd docs
-rm -rf source/torchvision
-cp -a ../vision/docs/source source/torchvision
 
 # Build the docs
-pip -q install -r requirements.txt || true
+pip -q install -r requirements.txt
 if [ "$is_master_doc" = true ]; then
-  # TODO: fix gh-38011 then enable this which changes warnings into errors
-  # export SPHINXOPTS="-WT --keep-going"
   make html
   make coverage
   # Now we have the coverage report, we need to make sure it is empty.

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    ?= -j auto
+SPHINXOPTS    ?= -j auto -WT --keep-going
 SPHINXBUILD   ?= sphinx-build
 SPHINXPROJ    ?= PyTorch
 SOURCEDIR     ?= source

docs/source/jit.rst

@@ -50,7 +50,6 @@ Creating TorchScript Code
     wait
     ScriptModule
     ScriptFunction
-    freeze
     save
     load
     ignore

docs/source/optim.rst

@@ -187,7 +187,7 @@ normalization statistics at the end of training.
 
 SWA has been proposed in `Averaging Weights Leads to Wider Optima and Better Generalization`_.
 
-.. _`Averaging Weights Leads to Wider Optima and Better Generalization` https://arxiv.org/abs/1803.05407
+.. _`Averaging Weights Leads to Wider Optima and Better Generalization`: https://arxiv.org/abs/1803.05407
 
 Constructing averaged models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

torch/__init__.py

@@ -272,6 +272,7 @@ def set_default_tensor_type(t):
 def set_default_dtype(d):
     r"""Sets the default floating point dtype to :attr:`d`.
     This dtype is:
+
     1. The inferred dtype for python floats in :func:`torch.tensor`.
     2. Used to infer dtype for python complex numbers. The default complex dtype is set to
        ``torch.complex128`` if default floating point dtype is ``torch.float64``,
@@ -282,7 +283,7 @@ def set_default_dtype(d):
     Args:
         d (:class:`torch.dtype`): the floating point dtype to make the default
 
-    Example::
+    Example:
         >>> # initial default for floating point is torch.float32
         >>> torch.tensor([1.2, 3]).dtype
         torch.float32

torch/functional.py

@@ -1063,7 +1063,8 @@ def atleast_3d(*tensors):
     Returns:
         output (Tensor or tuple of Tensors)
 
-    Example::
+    Example:
+
         >>> x = torch.tensor(0.5)
         >>> x
         tensor(0.5000)
@@ -1076,7 +1077,7 @@ def atleast_3d(*tensors):
         >>> torch.atleast_3d(y)
         tensor([[[-0.8079],
                 [ 0.7460]],
-
+                <BLANKLINE>
                 [[-1.1647],
                 [ 1.4734]]])
         >>> x = torch.randn(1,1,1)

torch/serialization.py

@@ -334,7 +334,7 @@ def save(obj, f: Union[str, os.PathLike, BinaryIO],
          pickle_module=pickle, pickle_protocol=DEFAULT_PROTOCOL, _use_new_zipfile_serialization=True) -> None:
     """Saves an object to a disk file.
 
-    See also: :ref:`recommend-saving-models`
+    See also: `saving-loading-tensors`
 
     Args:
         obj: saved object