Re-export rand distributions (#663)

* Re-export distribution trait and implemented dists

* Export from the crate module

* Adapt doc tests

* Run cargo fmt

* Re-export the whole rand crate. Adjust docs, readme and examples.

* Refactor ndarray-rand readme and changelog.

* Re-export rand-distr. Update docs accordingly.

Add hyperlinks where helpful.

* Keep stuff in sync

* Update docs to use rand_distr

* Add doc example to random_using with seedable rng (Isaac64)

* Run cargo fmt

* Remove extern crate from doc tests

* Remove extern crate from README

Author: LukeMathWalker

ndarray-rand/Cargo.toml

@@ -7,20 +7,22 @@ license = "MIT/Apache-2.0"
 
 repository = "https://github.com/rust-ndarray/ndarray"
 documentation = "https://docs.rs/ndarray-rand/"
+readme = "README.md"
 
 description = "Constructors for randomized arrays. `rand` integration for `ndarray`."
 
 keywords = ["multidimensional", "matrix", "rand", "ndarray"]
 
 [dependencies]
 ndarray = { version = "0.12.0", path = ".." }
+rand_distr = "0.2.1"
 
 [dependencies.rand]
 version = "0.7.0"
 features = ["small_rng"]
 
 [dev-dependencies]
-rand_distr = "0.2.1"
+rand_isaac = "0.2.0"
 
 [package.metadata.release]
 no-dev-version = true

ndarray-rand/README.md

@@ -0,0 +1,65 @@
+ndarray-rand
+============
+
+Constructors for randomized arrays: `rand`'s integration with `ndarray`.
+
+Example
+=======
+
+Generate a 2-dimensional array with shape `(2,5)` and elements drawn from a uniform distribution
+over the `(0., 10.)` interval:
+
+```rust
+use ndarray::Array;
+use ndarray_rand::RandomExt;
+use ndarray_rand::rand_distr::Uniform;
+
+fn main() {
+    let a = Array::random((2, 5), Uniform::new(0., 10.));
+    println!("{:8.4}", a);
+    // Example Output:
+    // [[  8.6900,   6.9824,   3.8922,   6.5861,   2.4890],
+    //  [  0.0914,   5.5186,   5.8135,   5.2361,   3.1879]]
+}
+```
+
+Dependencies
+============
+
+``ndarray-rand`` depends on ``rand`` 0.7.
+
+[`rand`](https://docs.rs/rand/0.7.0/rand/) and [`rand-distr`](https://docs.rs/rand_distr/0.2.1/rand_distr/) are 
+re-exported as sub-modules, `ndarray_rand::rand` and `ndarray_rand::rand_distr` respectively. 
+Please rely on these submodules for guaranteed version compatibility.
+
+If you want to use a random number generator or distribution from another crate
+with `ndarray-rand`, you need to make sure that the other crate also depends on the
+same version of `rand`. Otherwise, the compiler may return errors saying
+that the items are not compatible (e.g. that a type doesn't implement a
+necessary trait).
+
+Recent changes
+==============
+
+0.10.0
+------
+
+  - Require `rand` 0.7
+  - Require Rust 1.32 or later
+  - Re-export `rand` as a submodule, `ndarray_rand::rand`
+  - Re-export `rand-distr` as a submodule, `ndarray_rand::rand_distr`
+  
+Check _[Changelogs](https://github.com/rust-ndarray/ndarray/ndarray-rand/RELEASES.md)_ to see 
+the changes introduced in previous releases.
+
+
+License
+=======
+
+Dual-licensed to be compatible with the Rust project.
+
+Licensed under the Apache License, Version 2.0
+http://www.apache.org/licenses/LICENSE-2.0 or the MIT license
+http://opensource.org/licenses/MIT, at your
+option. This file may not be copied, modified, or distributed
+except according to those terms.

ndarray-rand/README.rst

@@ -0,0 +1,51 @@
+Recent Changes
+--------------
+
+- 0.10.0
+
+  - Require `rand` 0.7
+  - Require Rust 1.32 or later
+  - Re-export `rand` as a submodule, `ndarray_rand::rand`
+  - Re-export `rand-distr` as a submodule, `ndarray_rand::rand_distr`
+
+- 0.9.0
+
+  - Require rand 0.6
+
+- 0.8.0
+
+  - Require ndarray 0.12
+  - Require rand 0.5
+
+- 0.7.0
+
+  - Require ndarray 0.11
+  - Require rand 0.4
+
+- 0.6.1
+
+  - Clean up implementation of ``Array::random`` by @v-shmyhlo
+
+- 0.6.0
+
+  - Require ndarray 0.10.0
+
+- 0.5.0
+
+  - Require ndarray 0.9
+
+- 0.4.0
+
+  - Require ndarray 0.8
+
+- 0.3.0
+
+  - Require ndarray 0.7
+
+- 0.2.0
+
+  - Require ndarray 0.6
+
+- 0.1.0
+
+  - Initial release

ndarray-rand/RELEASES.md

@@ -6,33 +6,50 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Constructors for randomized arrays. `rand` integration for `ndarray`.
+//! Constructors for randomized arrays: `rand` integration for `ndarray`.
 //!
 //! See [**`RandomExt`**](trait.RandomExt.html) for usage examples.
 //!
-//! **Note:** `ndarray-rand` depends on `rand` 0.7. If you use any other items
-//! from `rand`, you need to specify a compatible version of `rand` in your
-//! `Cargo.toml`. If you want to use a RNG or distribution from another crate
-//! with `ndarray-rand`, you need to make sure that crate also depends on the
-//! correct version of `rand`. Otherwise, the compiler will return errors
-//! saying that the items are not compatible (e.g. that a type doesn't
-//! implement a necessary trait).
+//! ## Note
+//!
+//! `ndarray-rand` depends on [`rand` 0.7.0](https://docs.rs/rand/0.7.0/rand/).
+//!
+//! [`rand`](https://docs.rs/rand/0.7.0/rand/) and [`rand-distr`](https://docs.rs/rand_distr/0.2.1/rand_distr/)
+//! are re-exported as sub-modules, [`ndarray_rand::rand`](rand/index.html)
+//! and [`ndarray_rand::rand_distr`](rand_distr/index.html) respectively.
+//! Please rely on these submodules for guaranteed version compatibility.
+//!
+//! If you want to use a random number generator or distribution from another crate
+//! with `ndarray-rand`, you need to make sure that the other crate also depends on the
+//! same version of `rand`. Otherwise, the compiler will return errors saying
+//! that the items are not compatible (e.g. that a type doesn't implement a
+//! necessary trait).
 
-use rand::distributions::Distribution;
-use rand::rngs::SmallRng;
-use rand::{thread_rng, Rng, SeedableRng};
+use crate::rand::distributions::Distribution;
+use crate::rand::rngs::SmallRng;
+use crate::rand::{thread_rng, Rng, SeedableRng};
 
 use ndarray::ShapeBuilder;
 use ndarray::{ArrayBase, DataOwned, Dimension};
 
+/// [`rand`](https://docs.rs/rand/0.7.0/rand/), re-exported for convenience and version-compatibility.
+pub mod rand {
+    pub use rand::*;
+}
+
+/// [`rand-distr`](https://docs.rs/rand_distr/0.2.1/rand_distr/), re-exported for convenience and version-compatibility.
+pub mod rand_distr {
+    pub use rand_distr::*;
+}
+
 /// Constructors for n-dimensional arrays with random elements.
 ///
 /// This trait extends ndarray’s `ArrayBase` and can not be implemented
 /// for other types.
 ///
 /// The default RNG is a fast automatically seeded rng (currently
-/// [`rand::rngs::SmallRng`](https://docs.rs/rand/0.5/rand/rngs/struct.SmallRng.html)
-/// seeded from [`rand::thread_rng`](https://docs.rs/rand/0.5/rand/fn.thread_rng.html)).
+/// [`rand::rngs::SmallRng`](https://docs.rs/rand/0.7/rand/rngs/struct.SmallRng.html)
+/// seeded from [`rand::thread_rng`](https://docs.rs/rand/0.7/rand/fn.thread_rng.html)).
 ///
 /// Note that `SmallRng` is cheap to initialize and fast, but it may generate
 /// low-quality random numbers, and reproducibility is not guaranteed. See its
@@ -50,13 +67,9 @@ where
     /// overflows usize.
     ///
     /// ```
-    /// extern crate rand;
-    /// extern crate ndarray;
-    /// extern crate ndarray_rand;
-    ///
-    /// use rand::distributions::Uniform;
     /// use ndarray::Array;
     /// use ndarray_rand::RandomExt;
+    /// use ndarray_rand::rand_distr::Uniform;
     ///
     /// # fn main() {
     /// let a = Array::random((2, 5), Uniform::new(0., 10.));
@@ -74,6 +87,26 @@ where
     /// `distribution`, using a specific Rng `rng`.
     ///
     /// ***Panics*** if the number of elements overflows usize.
+    ///
+    /// ```
+    /// use ndarray::Array;
+    /// use ndarray_rand::RandomExt;
+    /// use ndarray_rand::rand::SeedableRng;
+    /// use ndarray_rand::rand_distr::Uniform;
+    /// use rand_isaac::isaac64::Isaac64Rng;
+    ///
+    /// # fn main() {
+    /// // Get a seeded random number generator for reproducibility (Isaac64 algorithm)
+    /// let seed = 42;
+    /// let mut rng = Isaac64Rng::seed_from_u64(seed);
+    ///
+    /// // Generate a random array using `rng`
+    /// let a = Array::random_using((2, 5), Uniform::new(0., 10.), &mut rng);
+    /// println!("{:8.4}", a);
+    /// // Example Output:
+    /// // [[  8.6900,   6.9824,   3.8922,   6.5861,   2.4890],
+    /// //  [  0.0914,   5.5186,   5.8135,   5.2361,   3.1879]]
+    /// # }
     fn random_using<Sh, IdS, R>(shape: Sh, distribution: IdS, rng: &mut R) -> ArrayBase<S, D>
     where
         IdS: Distribution<S::Elem>,
@@ -109,16 +142,13 @@ where
 /// A wrapper type that allows casting f64 distributions to f32
 ///
 /// ```
-/// extern crate rand;
-/// extern crate ndarray;
-/// extern crate ndarray_rand;
-///
-/// use rand::distributions::Normal;
 /// use ndarray::Array;
 /// use ndarray_rand::{RandomExt, F32};
+/// use ndarray_rand::rand_distr::Normal;
 ///
 /// # fn main() {
-/// let a = Array::random((2, 5), F32(Normal::new(0., 1.)));
+/// let distribution_f64 = Normal::new(0., 1.).expect("Failed to create normal distribution");
+/// let a = Array::random((2, 5), F32(distribution_f64));
 /// println!("{:8.4}", a);
 /// // Example Output:
 /// // [[ -0.6910,   1.1730,   1.0902,  -0.4092,  -1.7340],

ndarray-rand/src/lib.rs

@@ -1,6 +1,6 @@
 use ndarray::Array;
+use ndarray_rand::rand_distr::Uniform;
 use ndarray_rand::RandomExt;
-use rand::distributions::Uniform;
 
 #[test]
 fn test_dim() {