Repository: pyro-ppl/pyro

Issue:
Copied comment-docs to torch.distributions wrappers from corresponding sources. 
Was surprised not to find a little handy annotations, had to drill down to source make sure i'm using the parameter correctly. 


Discussion:
Certainly, i can try. Took a brief look.. 

- soo [that loop at bottom of `torch.py`](https://github.com/pyro-ppl/pyro/blob/891880f/pyro/distributions/torch.py#L339-L361) ought to grab the `_Dist`'s `__doc__` and set the `_PyroDist`'s `__doc__` attr to the same value? Is that how you see it?

- `napoleon` is easy to add to sphinx's `conf.py`.. never used it though, do i have to invoke it explicitly in the make routines?
* in the loop I think I'd keep the existing docstring and append the new docstring to it.  Our current docstring points to the original, and while I agree with you it's helpful to have the original docstring, it's also useful to keep a link to the base distribution.
* I believe we can just add napoleon to our dev requirements in [setup.py](https://github.com/pyro-ppl/pyro/blob/1.8.5/setup.py#L120-L137) and [docs/requirements.txt](https://github.com/pyro-ppl/pyro/blob/1.8.5/docs/requirements.txt). Let's see 🙂 
* Also you can format and lint our python code via `make format` and `make lint` respectively. That should help avoid these CI linting errors

Resolving patch:
diff --git a/docs/source/conf.py b/docs/source/conf.py
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -47,6 +47,7 @@
     "sphinx.ext.graphviz",  #
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
+    'sphinx.ext.napoleon',
 ]
 
 # Disable documentation inheritance so as to avoid inheriting
diff --git a/pyro/contrib/forecast/forecaster.py b/pyro/contrib/forecast/forecaster.py
--- a/pyro/contrib/forecast/forecaster.py
+++ b/pyro/contrib/forecast/forecaster.py
@@ -70,6 +70,8 @@ def model(self, zero_data, covariates):
     @property
     def time_plate(self):
         """
+        Helper to create a ``pyro.plate`` over time.
+
         :returns: A plate named "time" with size ``covariates.size(-2)`` and
             ``dim=-1``. This is available only during model execution.
         :rtype: :class:`~pyro.plate`
diff --git a/pyro/distributions/torch.py b/pyro/distributions/torch.py
--- a/pyro/distributions/torch.py
+++ b/pyro/distributions/torch.py
@@ -2,6 +2,8 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import math
+import re
+import textwrap
 
 import torch
 
@@ -334,6 +336,16 @@ def support(self):
         return constraints.interval(self._unbroadcasted_low, self._unbroadcasted_high)
 
 
+def _cat_docstrings(*docstrings):
+    result = "\n".join(textwrap.dedent(s.lstrip("\n")) for s in docstrings)
+    result = re.sub("\n\n+", "\n\n", result)
+    # Drop torch-specific lines.
+    result = "".join(
+        line for line in result.splitlines(keepends=True) if "xdoctest" not in line
+    )
+    return result
+
+
 # Programmatically load all distributions from PyTorch.
 __all__ = []
 for _name, _Dist in torch.distributions.__dict__.items():
@@ -354,10 +366,11 @@ def support(self):
     _PyroDist.__doc__ = """
     Wraps :class:`{}.{}` with
     :class:`~pyro.distributions.torch_distribution.TorchDistributionMixin`.
+
     """.format(
         _Dist.__module__, _Dist.__name__
     )
-
+    _PyroDist.__doc__ = _cat_docstrings(_PyroDist.__doc__, _Dist.__doc__)
     __all__.append(_name)
 
 


Test patch: