Skip to content

Commit fbfc58a

Browse files
funkillfunkill
committed
update original
1 parent 21b83d8 commit fbfc58a

File tree

26 files changed

+513
-125
lines changed

26 files changed

+513
-125
lines changed

‎rust-cookbook/.github/workflows/check-links.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: Links
2+
3+
on:
4+
workflow_dispatch:
5+
pull_request:
6+
branches:
7+
- master
8+
9+
jobs:
10+
linkChecker:
11+
runs-on: ubuntu-latest
12+
env:
13+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
14+
CACHE_KEY: cache-lychee-${{ github.sha }}
15+
permissions:
16+
pull-requests: write
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Link Checker
21+
id: lychee
22+
uses: lycheeverse/[email protected]
23+
with:
24+
fail: false
25+
checkbox: false
26+
output: ./lychee/out.md
27+
args: "--mode task --base . --config ./ci/lychee.toml ."
28+
29+
- name: Save lychee cache
30+
uses: actions/cache/save@v4
31+
if: always()
32+
with:
33+
path: .lycheecache
34+
key: ${{ steps.restore-cache.outputs.cache-primary-key || env.CACHE_KEY }} # fallback in case the cache wasn't created yet
35+
36+
- name: Post Comment on Pull Request
37+
if: github.event_name == 'pull_request' && steps.lychee.outputs.exit_code != 0
38+
run: |
39+
echo "The link checker found some issues. Please review the report below:" > comment.md
40+
echo "" >> comment.md
41+
cat ./lychee/out.md >> comment.md
42+
gh pr comment ${{ github.event.pull_request.number }} --body-file comment.md
43+
44+
- name: Fail Workflow
45+
if: github.event_name == 'pull_request' && steps.lychee.outputs.exit_code != 0
46+
run: exit 1

‎rust-cookbook/.github/workflows/deploy-mdbook.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Build and Deploy mdBook
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
workflow_dispatch:
8+
9+
jobs:
10+
build-and-deploy:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout code
15+
uses: actions/checkout@v3
16+
17+
- name: Set up cache for mdbook
18+
id: cache-mdbook
19+
uses: actions/cache@v3
20+
with:
21+
path: |
22+
~/.cargo/bin/mdbook
23+
key: mdbook-v0.4.43
24+
25+
- name: Install mdBook (if not cached)
26+
if: steps.cache-mdbook.outputs.cache-hit != 'true'
27+
run: |
28+
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.43/mdbook-v0.4.43-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C ~/.cargo/bin
29+
chmod +x ~/.cargo/bin/mdbook
30+
31+
- name: Build mdBook
32+
run: |
33+
mdbook build
34+
35+
- name: Deploy to GitHub Pages
36+
uses: peaceiris/actions-gh-pages@v4
37+
with:
38+
github_token: ${{ secrets.GITHUB_TOKEN }}
39+
publish_dir: ./book

‎rust-cookbook/.github/workflows/mdbook-test.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Test Rust Project
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- master
7+
workflow_dispatch:
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v3
15+
16+
- name: Set up Rust
17+
uses: actions-rust-lang/setup-rust-toolchain@v1
18+
with:
19+
cache: 'true'
20+
toolchain: nightly
21+
22+
- name: Run tests
23+
id: cargo_test
24+
run: |
25+
cargo +nightly test --test skeptic -- -Z unstable-options --format junit --report-time --test-threads=1 | tee ./TEST-cookbook.xml
26+
27+
- name: List files for debugging
28+
if: always()
29+
run: ls -R
30+
31+
- name: Publish Test Report
32+
uses: mikepenz/[email protected]
33+
if: always()
34+
with:
35+
fail_on_failure: true
36+
require_tests: true
37+
summary: ${{ steps.cargo_test.outputs.summary }}
38+
report_paths: '**/TEST-*.xml'

‎rust-cookbook/CONTRIBUTING.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -257,13 +257,11 @@ after the code sample.
257257
> generator [`rand::Rng`].
258258
>
259259
> The [distributions available are documented here][rand-distributions].
260-
> An example using the [`Normal`] distribution is shown below.
261260
262261
[uniform distribution]: https://en.wikipedia.org/wiki/Uniform_distribution_(continuous)
263262
[`Distribution::sample`]: https://docs.rs/rand/*/rand/distributions/trait.Distribution.html#tymethod.sample
264263
[`rand::Rng`]: https://docs.rs/rand/*/rand/trait.Rng.html
265264
[rand-distributions]: https://docs.rs/rand/*/rand/distributions/index.html
266-
[`Normal`]: https://docs.rs/rand/*/rand/distributions/struct.Normal.html
267265

268266
#### Code
269267

@@ -299,7 +297,7 @@ explanation in the description.
299297
> use rand::distributions::{Normal, Distribution};
300298
>
301299
> fn main() {
302-
> let mut rng = rand::thread_rng();
300+
> let mut rng = rand::rng();
303301
> let normal = Normal::new(2.0, 3.0);
304302
> let v = normal.sample(&mut rng);
305303
> println!("{} is from a N(2, 9) distribution", v)

‎rust-cookbook/Cargo.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,8 @@ num_cpus = "1.16"
3636
percent-encoding = "2.3"
3737
petgraph = "0.6"
3838
postgres = "0.19"
39-
rand = "0.8"
40-
rand_distr = "0.4"
39+
rand = "0.9"
40+
rand_distr = "0.5.1"
4141
rayon = "1.10"
4242
regex = "1.11"
4343
reqwest = { version = "0.12", features = ["blocking", "json", "stream"] }

‎rust-cookbook/DEPLOYMENT.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Deployment Guide
2+
3+
This document explains how the Rust Cookbook is deployed locally by maintainers.
4+
5+
## Overview
6+
7+
The project uses local deployment scripts to build and deploy to GitHub Pages. This approach allows maintainers to deploy without needing GitHub Actions workflow permissions.
8+
9+
## Local Deployment
10+
11+
### Deployment Script (`scripts/deploy.sh`)
12+
13+
The deployment script handles:
14+
- **Building**: Builds the mdbook and copies assets
15+
- **Testing**: Runs cargo tests and spellcheck
16+
- **Deployment**: Pushes the built site to the `gh-pages` branch
17+
18+
### Makefile Commands
19+
20+
For convenience, a Makefile provides easy commands:
21+
22+
```bash
23+
make help # Show all available commands
24+
make build # Build the book locally
25+
make test # Run all tests
26+
make dev # Build and test (development workflow)
27+
make deploy # Deploy to GitHub Pages
28+
make serve # Serve locally with live reload
29+
make clean # Clean build artifacts
30+
```
31+
32+
## Local Development
33+
34+
For local development and testing:
35+
36+
```bash
37+
# Use the Makefile (recommended)
38+
make dev
39+
40+
# Or run the development script
41+
./scripts/dev.sh
42+
43+
# Or manually:
44+
cargo install mdbook --vers "0.4.43"
45+
mdbook build
46+
cp -r assets/ book/
47+
cargo test
48+
./ci/spellcheck.sh list
49+
```
50+
51+
## GitHub Pages Configuration
52+
53+
The site is deployed to GitHub Pages from the `gh-pages` branch. The GitHub Actions workflow automatically:
54+
1. Builds the mdbook to the `book/` directory
55+
2. Copies assets from `assets/` to `book/`
56+
3. Pushes the contents to the `gh-pages` branch
57+
4. GitHub Pages serves the site from this branch
58+
59+
## Troubleshooting
60+
61+
### Build Failures
62+
- Check the GitHub Actions logs for specific error messages
63+
- Ensure all code examples compile and pass tests
64+
- Verify that all links in the documentation are valid
65+
66+
### Deployment Issues
67+
- Ensure the repository has GitHub Pages enabled in Settings > Pages
68+
- Check that the `GITHUB_TOKEN` secret is available (this is automatic for public repositories)
69+
- Verify that the `gh-pages` branch is being created and updated
70+
71+
### Local Build Issues
72+
- Make sure you have Rust and Cargo installed
73+
- Install mdbook with the exact version: `cargo install mdbook --vers "0.4.43"`
74+
- Run `cargo clean` if you encounter dependency issues
75+
76+
## Migration from Travis CI
77+
78+
This setup replaces the previous Travis CI configuration:
79+
- `ci/deploy.sh` - Replaced by local deployment script (`scripts/deploy.sh`)
80+
- `ci/test_script.sh` - Functionality integrated into local scripts
81+
- `appveyor.yml` - Windows testing can be added if needed
82+
83+
The new setup provides the same functionality while allowing maintainers to deploy without needing GitHub Actions workflow permissions.

‎rust-cookbook/Makefile‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.PHONY: help build test deploy deploy-skip-tests dev clean install-mdbook
2+
3+
help: ## Show this help message
4+
@echo "Rust Cookbook - Available commands:"
5+
@echo ""
6+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
7+
8+
install-mdbook: ## Install mdbook with the correct version
9+
cargo install mdbook --vers "0.4.43"
10+
11+
build: install-mdbook ## Build the book locally
12+
mdbook build
13+
cp -r assets/ book/
14+
@echo "Build complete! Open book/index.html in your browser."
15+
16+
test: ## Run all tests
17+
cargo test
18+
./ci/spellcheck.sh list
19+
20+
dev: build test ## Build and test (development workflow)
21+
@echo "Development build complete!"
22+
23+
deploy: dev ## Deploy to GitHub Pages (requires maintainer permissions)
24+
./scripts/deploy.sh
25+
26+
deploy-skip-tests: build ## Deploy to GitHub Pages without running tests
27+
./scripts/deploy.sh --skip-tests
28+
29+
clean: ## Clean build artifacts
30+
cargo clean
31+
rm -rf book/
32+
@echo "Clean complete!"
33+
34+
serve: install-mdbook ## Serve the book locally with live reload
35+
mdbook serve --open

‎rust-cookbook/README.md‎

Lines changed: 48 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
# A Rust Cookbook   [![Build Status travis]][travis]
1+
# A Rust Cookbook   [![Build Status][build-badge]][build-url]
22

3-
[Build Status travis]: https://api.travis-ci.com/rust-lang-nursery/rust-cookbook.svg?branch=master
4-
[travis]: https://travis-ci.com/rust-lang-nursery/rust-cookbook
3+
[build-badge]: https://github.com/rust-lang-nursery/rust-cookbook/workflows/Deploy%20to%20GitHub%20Pages/badge.svg
4+
[build-url]: https://github.com/rust-lang-nursery/rust-cookbook/actions?query=workflow%3A%22Deploy+to+GitHub+Pages%22
55

66
**[Read it here]**.
77

@@ -31,6 +31,51 @@ $ start .\book\index.html # windows
3131
$ open ./book/index.html # mac
3232
```
3333

34+
## Development
35+
36+
### Local Development
37+
38+
For local development and testing, you can use the provided Makefile:
39+
40+
```bash
41+
# Show all available commands
42+
make help
43+
44+
# Build the book locally
45+
make build
46+
47+
# Run tests
48+
make test
49+
50+
# Build and test (development workflow)
51+
make dev
52+
53+
# Serve the book locally with live reload
54+
make serve
55+
56+
# Clean build artifacts
57+
make clean
58+
```
59+
60+
### Deployment
61+
62+
As a maintainer, you can deploy the site locally using:
63+
64+
```bash
65+
# Deploy to GitHub Pages (requires maintainer permissions)
66+
make deploy
67+
68+
# Or use the script directly
69+
./scripts/deploy.sh
70+
```
71+
72+
The deployment script will:
73+
1. Build and test the book
74+
2. Push the built site to the `gh-pages` branch
75+
3. GitHub Pages will automatically serve the updated site
76+
77+
**Note**: This requires maintainer permissions to push to the `gh-pages` branch.
78+
3479
[Read it here]: https://rust-lang-nursery.github.io/rust-cookbook
3580
[Rust]: https://www.rust-lang.org/
3681

‎rust-cookbook/ci/dictionary.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -348,4 +348,4 @@ YYYY
348348
zurich
349349
enum
350350
thiserror
351-
tempfile
351+
tempfile

‎rust-cookbook/ci/lychee.toml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Don't show interactive progress bar while checking links.
2+
no_progress = true
3+
4+
# Enable link caching. This can be helpful to avoid checking the same links on
5+
# multiple runs.
6+
cache = true
7+
8+
# Discard all cached requests older than this duration.
9+
max_cache_age = "2d"
10+
11+
user_agent = "curl/7.83. 1"
12+
13+
# Website timeout from connect to response finished.
14+
timeout = 20
15+
16+
# Minimum wait time in seconds between retries of failed requests.
17+
retry_wait_time = 20
18+
19+
# Comma-separated list of accepted status codes for valid links.
20+
accept = ["200", "429"] # 429 for ratelimits
21+
22+
# Request method
23+
method = "get"
24+
25+
# Custom request headers
26+
headers = []
27+
28+
# Exclude loopback IP address range and localhost from checking.
29+
exclude_loopback = false
30+
31+
# Check mail addresses
32+
include_mail = true

0 commit comments

Comments
 (0)