Merge pull request #81 from rust-random/push-kyrypuxtmnlu

Fix guide links; guide tweaks

Author: dhardy

.github/workflows/gh-pages.yml

@@ -10,13 +10,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-
-      - name: Setup mdBook
-        uses: peaceiris/actions-mdbook@v2
+      - uses: jontze/action-mdbook@6c0be56d14c4bf16861b00af61f50ff7400ce502 # v4
         with:
-          mdbook-version: '0.4.4'
-          # mdbook-version: 'latest'
-
+          token: ${{secrets.GITHUB_TOKEN}}
+          use-linkcheck: true
       - run: mdbook build
 
       - name: Deploy

.github/workflows/test.yml

@@ -7,6 +7,17 @@ on:
     branches: [ master, '0.[0-9]+' ]
 
 jobs:
+  build:
+    name: Test building of docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: jontze/action-mdbook@6c0be56d14c4bf16861b00af61f50ff7400ce502 # v4
+        with:
+          token: ${{secrets.GITHUB_TOKEN}}
+          use-linkcheck: true
+      - run: mdbook build
+
   code-samples:
     name: Test code samples
     runs-on: ubuntu-latest

book.toml

@@ -7,3 +7,6 @@ description = "Extended documentation for Rust's Rand lib"
 
 [output.html.playgen]
 editable = true
+
+[output.linkcheck]
+# NOTE: this requires https://github.com/Michael-F-Bryan/mdbook-linkcheck

src/SUMMARY.md

@@ -21,7 +21,7 @@
     - [Random processess](guide-process.md)
     - [Sequences](guide-seq.md)
     - [Error handling](guide-err.md)
-    - [Testing functions that use RNGs](guide-test-fn-rng.md)
+    - [Testing randomized functions](guide-test-fn-rng.md)
 
 - [Updating](update.md)
     - [Updating to 0.5](update-0.5.md)

src/crate-features.md

@@ -1,31 +1,25 @@
 # Crate features
 
-For definitive documentation of crate features, check the crate release's `Cargo.toml`:
+It is recommended to check the crate's `Cargo.toml` or `README.md` for features.
+Since `rand v0.9`, `rust-random` crates only use explicit features (i.e. all
+features are listed under `[features]`).
+
+Release versions of `Cargo.toml` can be viewed on `docs.rs`:
 
 -   <https://docs.rs/crate/rand/latest/source/Cargo.toml.orig>
 -   <https://docs.rs/crate/rand_core/latest/source/Cargo.toml.orig>
 -   <https://docs.rs/crate/rand_distr/latest/source/Cargo.toml.orig>
+-   <https://docs.rs/crate/rand_chacha/latest/source/Cargo.toml.orig>
+-   <https://docs.rs/crate/rand_xoshiro/latest/source/Cargo.toml.orig>
+-   <https://docs.rs/crate/rand_pcg/latest/source/Cargo.toml.orig>
 
 ## Common features
 
 The following features are common to `rand_core`, `rand`, `rand_distr` and potentially some RNG crates:
 
 -   `std`: opt into functionality dependent on the `std` lib. This is default-enabled except in `rand_core`; for `no_std` usage, use `default-features = false`.
 -   `alloc`: enables functionality requiring an allocator (for usage with `no_std`). This is implied by `std`.
--   `serde1`: enables serialization via [`serde`], version 1.0.
-
-## Rand features
-
-Additional `rand` features:
-
--   `small_rng` enables the [`SmallRng`] generator (feature-gated since v0.7).
--   `simd_support`: Experimental support for generating various SIMD types (requires nightly `rustc`).
--   `log` enables a few log messages via [`log`].
-
-Note regarding SIMD: the above flag concerns explicit generation of SIMD types
-only and not optimisation. SIMD operations may be used internally regardless of
-this flag; e.g. the ChaCha generator has explicit support for SIMD operations
-internally.
+-   `serde`: enables serialization via [`serde`], version 1.0.
 
 ## rand_distr features
 
@@ -36,3 +30,4 @@ performance but may produce different random values, the `std_math` feature
 can be enabled. (Note that any other crate depending on `num-traits`'s `std` feature (default-enabled) will have the same effect.)
 
 [`SmallRng`]: https://docs.rs/rand/latest/rand/rngs/struct.SmallRng.html
+[`serde`]: https://serde.rs/

src/guide-rngs.md

@@ -2,7 +2,7 @@
 
 There are many kinds of RNGs, with different trade-offs. Rand provides some
 convenient generators in the [`rngs` module]. Often you can just use
-[`thread_rng`], a function which automatically initializes an RNG in
+[`rand::rng`], a function which automatically initializes an RNG in
 thread-local memory and returns a reference to it. It is fast, good quality,
 and (to the best of our knowledge) cryptographically secure.
 
@@ -304,7 +304,7 @@ by P. Hellekalek.
 [`SmallRng`]: https://docs.rs/rand/latest/rand/rngs/struct.SmallRng.html
 [`StdRng`]: https://docs.rs/rand/latest/rand/rngs/struct.StdRng.html
 [`StepRng`]: https://docs.rs/rand/latest/rand/rngs/mock/struct.StepRng.html
-[`rng()`]: https://docs.rs/rand/latest/rand/fn.rng.html
+[`rand::rng`]: https://docs.rs/rand/latest/rand/fn.rng.html
 [basic PRNGs]: #basic-pseudo-random-number-generators-prngs
 [CSPRNGs]: #cryptographically-secure-pseudo-random-number-generators-csprngs
 [`Pcg32`]: https://docs.rs/rand_pcg/latest/rand_pcg/type.Pcg32.html

src/guide-seeding.md

@@ -8,6 +8,10 @@ key, usually specified as a byte-sequence for cryptographic generators or,
 for small PRNGs, often just a word. We formalise this for all our generators
 with the [`SeedableRng`] trait.
 
+Note: seeding does not imply reproducibility of results. For that you need to
+use a named RNG with a fixed algorithm (e.g. `ChaCha12Rng` not `StdRng`). See
+also [Reproducibility](https://rust-random.github.io/book/crate-reprod.html).
+
 ## The Seed type
 
 We require all seedable RNGs to define a [`Seed`] type satisfying

src/guide-test-fn-rng.md

@@ -1,4 +1,4 @@
-# Testing functions that use RNGs
+# Testing functions which use RNGs
 
 Occasionally a function that uses random number generators might need to be tested. For functions that need to be tested with test vectors, the following approach might be adapted:
 

src/guide-values.md

@@ -132,4 +132,5 @@ fn main() {
 [`Rng::try_fill`]: https://docs.rs/rand/latest/rand/trait.Rng.html#method.try_fill
 [`random`]: https://docs.rs/rand/latest/rand/fn.random.html
 [`rng()`]: https://docs.rs/rand/latest/rand/fn.rng.html
+[`Distribution`]: https://docs.rs/rand/latest/rand/distr/trait.Distribution.html
 [`StandardUniform`]: https://docs.rs/rand/latest/rand/distr/struct.StandardUniform.html

src/guide.md

@@ -2,14 +2,18 @@
 
 This section attempts to explain some of the concepts used in this library.
 
-1.  [Getting started with a new crate](guide-cargo.md)
+1.  [Getting started with a new crate](guide-start.md)
 1.  [What is random data and what is randomness anyway?](guide-data.md)
 1.  [What kind of random generators are there?](guide-gen.md)
 1.  [What random number generators does Rand provide?](guide-rngs.md)
+1.  [Seeding PRNGs and reproducibility](guide-seeding.md)
+1.  [Parallel RNGs](guide-parallel.md)
 1.  [Turning random data into useful values](guide-values.md)
 1.  [Distributions: more control over random values](guide-dist.md)
+1.  [Random processes: sampling without replacement](guide-process.md)
 1.  [Sequences](guide-seq.md)
 1.  [Error handling](guide-err.md)
+1.  [Testing functions which use RNGs](guide-test-fn-rng.md)
 
 ## Importing items (prelude)