[ready] General documentation improvements (pytorch#5450)

* Improvize documentation
1. Add formula for erf, erfinv
2. Make exp, expm1 similar to log, log1p
3. Symbol change in ge, le, ne, isnan

* Fix minor nit in the docstring

* More doc improvements
1. Added some formulae
2. Complete scanning till "Other Operations" in Tensor docs

* Add more changes
1. Modify all torch.Tensor wherever required

* Fix Conv docs
1. Fix minor nits in the references for LAPACK routines

* Improve Pooling docs
1. Fix lint error

* Improve docs for RNN, Normalization and Padding
1. Fix flake8 error for pooling

* Final fixes for torch.nn.* docs.
1. Improve Loss Function documentation
2. Improve Vision Layers documentation

* Fix lint error

* Improve docstrings in torch.nn.init

* Fix lint error

* Fix minor error in torch.nn.init.sparse

* Fix Activation and Utils Docs
1. Fix Math Errors
2. Add explicit clean to Makefile in docs to prevent running graph generation script
while cleaning
3. Fix utils docs

* Make PYCMD a Makefile argument, clear up prints in the build_activation_images.py

* Fix batch norm doc error

Author: vishwakftw

docs/Makefile

@@ -7,13 +7,14 @@ SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = PyTorch
 SOURCEDIR     = source
 BUILDDIR      = build
+PYCMD         = python
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 figures:
-	python source/scripts/build_activation_images.py
+	@$(PYCMD) source/scripts/build_activation_images.py
 
 docset: html
 	doc2dash --name $(SPHINXPROJ) --icon $(SOURCEDIR)/_static/img/pytorch-logo-flame.png --enable-js --online-redirect-url http://pytorch.org/docs/ --force $(BUILDDIR)/html/
@@ -28,3 +29,7 @@ docset: html
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile figures
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	@echo "Removing everything under 'build'.."
+	@rm -r $(BUILDDIR)/html/ $(BUILDDIR)/doctrees

docs/source/scripts/build_activation_images.py

@@ -67,7 +67,6 @@ def plot_function(function, **args):
     plot_path = os.path.join(ACTIVATION_IMAGE_PATH, function_name + ".png")
     if not os.path.exists(plot_path):
         function = torch.nn.modules.activation.__dict__[function_name]()
-        print(function)
 
         # Start a new plot
         pylab.clf()
@@ -91,5 +90,5 @@ def plot_function(function, **args):
         pylab.ylim([-7, 7])
 
         # And save it
-        print(plot_path)
         pylab.savefig(plot_path)
+        print('Saved activation image for {} at {}'.format(function, plot_path))

torch/__init__.py

@@ -110,7 +110,7 @@ def typename(o):
 
 
 def is_tensor(obj):
-    r"""Returns True if `obj` is a pytorch tensor.
+    r"""Returns True if `obj` is a PyTorch tensor.
 
     Args:
         obj (Object): Object to test
@@ -119,7 +119,7 @@ def is_tensor(obj):
 
 
 def is_storage(obj):
-    r"""Returns True if `obj` is a pytorch storage object.
+    r"""Returns True if `obj` is a PyTorch storage object.
 
     Args:
         obj (Object): Object to test

torch/_storage_docs.py

@@ -28,13 +28,14 @@ def add_docstr_all(method, docstr):
                """
 from_file(filename, shared=False, size=0) -> Storage
 
-If shared is True then memory is shared between all processes. All changes are
-written to the file. If shared is False then the changes on the storage do not
-affect the file.
-
-Size is the number of elements in the storage. If shared is False then the file
-must contain at least `size * sizeof(Type)` bytes (`Type` is the type of
-storage). If shared is True the file will be created if needed.
+If `shared` is `True`, then memory is shared between all processes.
+All changes are written to the file. If `shared` is `False`, then the changes on
+the storage do not affect the file.
+
+`size` is the number of elements in the storage. If `shared` is `False`,
+then the file must contain at least `size * sizeof(Type)` bytes
+(`Type` is the type of storage). If `shared` is `True` the file will be
+created if needed.
 
 Args:
     filename (str): file name to map

torch/_tensor_docs.py

@@ -259,7 +259,7 @@ def add_docstr_all(method, docstr):
 
 .. math::
 
-    P(x) = \dfrac{1}{\pi} \dfrac{\sigma}{(x - median)^2 + \sigma^2}
+    f(x) = \dfrac{1}{\pi} \dfrac{\sigma}{(x - median)^2 + \sigma^2}
 """)
 
 add_docstr_all('ceil',
@@ -514,7 +514,7 @@ def add_docstr_all(method, docstr):
 
 .. math::
 
-    P(x) = \lambda e^{-\lambda x}
+    f(x) = \lambda e^{-\lambda x}
 """)
 
 add_docstr_all('fill_',
@@ -602,7 +602,7 @@ def add_docstr_all(method, docstr):
 
 .. math::
 
-    P(X=k) = (1 - p)^{k - 1} p
+    f(X=k) = (1 - p)^{k - 1} p
 
 """)
 
@@ -861,7 +861,7 @@ def add_docstr_all(method, docstr):
 
 .. math::
 
-    P(x) = \\dfrac{1}{x \\sigma \\sqrt{2\\pi}}\ e^{-\\dfrac{(\\ln x - \\mu)^2}{2\\sigma^2}}
+    f(x) = \\dfrac{1}{x \\sigma \\sqrt{2\\pi}}\ e^{-\\dfrac{(\\ln x - \\mu)^2}{2\\sigma^2}}
 """)
 
 add_docstr_all('lt',

torch/_tensor_str.py

@@ -23,20 +23,20 @@ def set_printoptions(
         linewidth=None,
         profile=None,
 ):
-    """Set options for printing. Items shamelessly taken from Numpy
+    r"""Set options for printing. Items shamelessly taken from NumPy
 
     Args:
         precision: Number of digits of precision for floating point output
-            (default 8).
+            (default = 8).
         threshold: Total number of array elements which trigger summarization
-            rather than full repr (default 1000).
+            rather than full `repr` (default = 1000).
         edgeitems: Number of array items in summary at beginning and end of
-            each dimension (default 3).
+            each dimension (default = 3).
         linewidth: The number of characters per line for the purpose of
-            inserting line breaks (default 80). Thresholded matricies will
+            inserting line breaks (default = 80). Thresholded matricies will
             ignore this parameter.
         profile: Sane defaults for pretty printing. Can override with any of
-            the above options. (default, short, full)
+            the above options. (any one of `default`, `short`, `full`)
     """
     if profile is not None:
         if profile == "default":