Following discussion on Discourse, this PR expands the documentation
for defining custom random samplers. Motivation is provided for the
design, followed by examples that gradually introduce features and
explain why/when they should be used.

No text was removed, but some parts were moved to other subsections.

Docstrings added for relevant methods and structures, and included in
the docs.

The use of pre-existing types is emphasized.

- clarify role of `gentype`

- use `sp` as an argument name for samplers

- corrections for docstrings

- clarify pedagogical motivation for custom samplers not using
  existing types

- various minor text corrections: spaces, emphases

Co-Authored-By: tpapp <[email protected]>

This was making Documenter fail.