Expand DensityDist docstrings

[ricardoV94]

We should include code snippets about how to use the DensityDist, as 1) the API has changed since V3, and 2) it has always been a source of confusion

pymc/pymc/distributions/distribution.py

Lines 680 to 686 in 7a6bd02

	class DensityDist(NoDistribution):
	"""A distribution that can be used to wrap black-box log density functions.
	Creates a Distribution and registers the supplied log density function to be used
	for inference. It is also possible to supply a `random` method in order to be able
	to sample from the prior or posterior predictive distributions.
	"""

We should also add a warning, similar to the Interval transform, stating the logp / logcdf / random / get_moment functions cannot rely on nonlocal variables, but only on constants + distribution parameters:

pymc/pymc/distributions/transforms.py

Lines 204 to 207 in 7a6bd02

	.. warning:: Expressions returned by `bounds_fn` should depend only on the
	distribution inputs or other constants. Expressions that depend on other
	symbolic variables, including nonlocal variables defined in the model
	context will likely break sampling.

See #5614 and related issue for more context on this limitation

Bonus points for including an example of a Multivariate distribution and explaining ndim_supp and ndim_params

Not everything has to be done at once or by the same person!

[OriolAbril]

Also, the __new__ method should have no docstring. All the content there should be in the class docstring, otherwise it doesn't appear in the documentation

[ricardoV94]

Also, the __new__ method should have no docstring. All the content there should be in the class docstring, otherwise it doesn't appear in the documentation

Created a specific issue for that: #6031

[ricardoV94]

There have been a couple of PRs improving the status. I think this can be closed

https://docs.pymc.io/en/latest/api/distributions/generated/pymc.CustomDist.html

[OriolAbril]

closing then, it still needs to be fixed to comply with #5459 but there is already that other issue open for this.