Factored out sample function

[tbekolay]

Motivation and context:
The ensemble tuning function in #871 needed access to the builder's sample function. We're moving #871 to nengo_extras, but it's a good idea to move the sample function anyhow, as it's used in several places.

Originally @drasmuss moved this to nengo.utils.builder; I figured it's not bad to have in nengo.dists. Though, since it's not quite the same as Distribution.sample we should perhaps rename it to something? sample_if_needed or something?

Interactions with other PRs:
Supercedes #871.

How has this been tested?
Ran the test suite locally. Doesn't require additional testing.

How long should this take to review?

• Quick (less than 40 lines changed or changes are straightforward)

Types of changes:

• New feature (non-breaking change which adds functionality)

Checklist:

• I have read the CONTRIBUTING.rst document.
• I have updated the documentation accordingly.
• I have included a changelog entry.
• [NA] I have added tests to cover my changes.
• All new and existing tests passed.

Still to do:

• We should decide if we're okay with having this in nengo.dists, and whether we should keep it named sample or something more explicit.
• Changelog entry (once we decide the point above) since it maybe become part of the frontend API.

[jgosmann]

How about get_samples? That name would agnostic to whether the samples are obtained by sampling or just returning existing samples.

[tbekolay]

How about get_samples?

Yeah, I can see that! What do you think about renaming the first argument to dist_or_samples? Seems to cover all the bases

[jgosmann]

What do you think about renaming the first argument to dist_or_samples?

I'm fine with that; I'm also fine with dist.

[drasmuss]

Renaming and relocation both sound fine to me.

[jgosmann]

LGTM 🍰

[Seanny123]

LGTM.

[tbekolay]

In order to check all the boxes above, I added a docstring, then realized we don't have the distributions anywhere in the docs. So I added them (and fixed up our current docstrings to print nicely) in ef5d221 and added the docstring and a changelog entry. I think those don't warrant two re-reviews, so @jgosmann can you take a look at this and merge if they look good to you?