* API: restructure and document numpy.random C-API

* DOC: fix bad reference

* API: ship, document, and start to test numpy.random C-API examples

* API, DOC, TST: fix tests, refactor documentation to include snippets

* BUILD: move public headers to numpy/core/include/numpy/random

* TST: ignore DeprecationWarnings in setuptools and numba

* DOC: document the C-API as used from Cython

The new method

  multivariate_hypergeometric(self, object colors, object nsample,
                              size=None, method='marginals')

of the class numpy.random.Generator implements the multivariate
hypergeometric distribution; see
  https://en.wikipedia.org/wiki/Hypergeometric_distribution,
specifically the section "Multivariate hypergeometric distribution".

Two algorithms are implemented.  The user selects which algorithm
to use with the `method` parameter. The default, `method='marginals'`,
is based on repeated calls of the univariate hypergeometric
distribution function.  The other algorithm, selected with
`method='count'`, is a brute-force method that allocates an
internal array of length ``sum(colors)``.  It should only be used
when that value is small, but it can be much faster than the
"marginals" algorithm in that case.

The C implementations of the two methods are in the files
random_mvhg_count.c and random_mvhg_marginals.c in
numpy/random/src/distributions.