[chore] Documentation fixes, no more ref issues and more API fields (#103)

* various fixes, no more issues with `make html` and more API fields should be populated

docs/source/api/nn/pipe.rst

@@ -2,3 +2,5 @@ Pipe
 ====
 
 .. autoclass:: fairscale.nn.Pipe
+    :members:
+    :undoc-members:

docs/source/api/optim/oss.rst

@@ -2,3 +2,5 @@ OSS
 ====
 
 .. autoclass:: fairscale.optim.OSS
+    :members:
+    :undoc-members:

docs/source/conf.py

@@ -37,9 +37,7 @@ release = "0.0.2"
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    "sphinx.ext.autodoc",
-]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosectionlabel"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

fairscale/nn/pipe/pipe.py

@@ -290,7 +290,7 @@ class Pipe(Module):
             ``'except_last'``, or ``'never'`` (default: ``'except_last'``)
         deferred_batch_norm (bool):
             whether to use deferred BatchNorm moving statistics (default:
-            :data:`False`, see :ref:`Deferred Batch Normalization` for more
+            :data:`False`, see :class:`DeferredBatchNorm` for more
             details)
         pipelined_backward (bool, optional):
             if True, call torch.autograd.backward once per microbatch on the
@@ -527,15 +527,15 @@ class Pipe(Module):
         return super().cpu()
 
     def to(self, *args: Any, **kwargs: Any) -> "Pipe":
-        # Deny these usages:
-        #
-        # - to(device[, dtype, non_blocking])
-        # - to(tensor[, non_blocking])
-        #
-        # But allow this:
-        #
-        # - to(dtype[, non_blocking])
-        #
+        """ Restrict .to() options.
+
+        Deny these usages:
+         - to(device[, dtype, non_blocking])
+         - to(tensor[, non_blocking])
+
+         But allow this:
+         - to(dtype[, non_blocking])
+        """
         if self.devices:
             if "device" in kwargs or "tensor" in kwargs:
                 raise MOVING_DENIED

fairscale/optim/oss.py

@@ -16,6 +16,8 @@ from torch.optim import SGD, Optimizer
 
 from .utils import broadcast_object, recursive_copy_to_device
 
+__all__ = ["OSS"]
+
 if TYPE_CHECKING:  # pragma: no cover
     from torch.optim.optimizer import _params_t
 else:
@@ -25,7 +27,9 @@ else:
 class OSS(Optimizer):
     """Wraps an arbitrary :class:`optim.Optimizer <torch.optim.Optimizer>`
     optimizer and shards its state as described by ZeRO_.
-    :: opt = OSS(params, optim=torch.optim.Adam, lr=0.01)
+    ::
+
+        opt = OSS(params, optim=torch.optim.Adam, lr=0.01)
 
     .. _ZeRO: https://arxiv.org/abs/1910.02054