Devx/deployment guide

DEPLOYMENT.md

@@ -0,0 +1,83 @@
+# Deployment Guide
+
+This document explains how the Rust Cookbook is deployed locally by maintainers.
+
+## Overview
+
+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.
+
+## Local Deployment
+
+### Deployment Script (`scripts/deploy.sh`)
+
+The deployment script handles:
+- **Building**: Builds the mdbook and copies assets
+- **Testing**: Runs cargo tests and spellcheck
+- **Deployment**: Pushes the built site to the `gh-pages` branch
+
+### Makefile Commands
+
+For convenience, a Makefile provides easy commands:
+
+```bash
+make help      # Show all available commands
+make build     # Build the book locally
+make test      # Run all tests
+make dev       # Build and test (development workflow)
+make deploy    # Deploy to GitHub Pages
+make serve     # Serve locally with live reload
+make clean     # Clean build artifacts
+```
+
+## Local Development
+
+For local development and testing:
+
+```bash
+# Use the Makefile (recommended)
+make dev
+
+# Or run the development script
+./scripts/dev.sh
+
+# Or manually:
+cargo install mdbook --vers "0.4.43"
+mdbook build
+cp -r assets/ book/
+cargo test
+./ci/spellcheck.sh list
+```
+
+## GitHub Pages Configuration
+
+The site is deployed to GitHub Pages from the `gh-pages` branch. The GitHub Actions workflow automatically:
+1. Builds the mdbook to the `book/` directory
+2. Copies assets from `assets/` to `book/`
+3. Pushes the contents to the `gh-pages` branch
+4. GitHub Pages serves the site from this branch
+
+## Troubleshooting
+
+### Build Failures
+- Check the GitHub Actions logs for specific error messages
+- Ensure all code examples compile and pass tests
+- Verify that all links in the documentation are valid
+
+### Deployment Issues
+- Ensure the repository has GitHub Pages enabled in Settings > Pages
+- Check that the `GITHUB_TOKEN` secret is available (this is automatic for public repositories)
+- Verify that the `gh-pages` branch is being created and updated
+
+### Local Build Issues
+- Make sure you have Rust and Cargo installed
+- Install mdbook with the exact version: `cargo install mdbook --vers "0.4.43"`
+- Run `cargo clean` if you encounter dependency issues
+
+## Migration from Travis CI
+
+This setup replaces the previous Travis CI configuration:
+- `ci/deploy.sh` - Replaced by local deployment script (`scripts/deploy.sh`)
+- `ci/test_script.sh` - Functionality integrated into local scripts
+- `appveyor.yml` - Windows testing can be added if needed
+
+The new setup provides the same functionality while allowing maintainers to deploy without needing GitHub Actions workflow permissions. 

Makefile

@@ -0,0 +1,35 @@
+.PHONY: help build test deploy deploy-skip-tests dev clean install-mdbook
+
+help: ## Show this help message
+	@echo "Rust Cookbook - Available commands:"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install-mdbook: ## Install mdbook with the correct version
+	cargo install mdbook --vers "0.4.43"
+
+build: install-mdbook ## Build the book locally
+	mdbook build
+	cp -r assets/ book/
+	@echo "Build complete! Open book/index.html in your browser."
+
+test: ## Run all tests
+	cargo test
+	./ci/spellcheck.sh list
+
+dev: build test ## Build and test (development workflow)
+	@echo "Development build complete!"
+
+deploy: dev ## Deploy to GitHub Pages (requires maintainer permissions)
+	./scripts/deploy.sh
+
+deploy-skip-tests: build ## Deploy to GitHub Pages without running tests
+	./scripts/deploy.sh --skip-tests
+
+clean: ## Clean build artifacts
+	cargo clean
+	rm -rf book/
+	@echo "Clean complete!"
+
+serve: install-mdbook ## Serve the book locally with live reload
+	mdbook serve --open 

README.md

@@ -1,8 +1,7 @@
-# A Rust Cookbook   [![Build Status travis]][travis]
+# A Rust Cookbook   [![Build Status][build-badge]][build-url]
 
-[Build Status travis]: https://api.travis-ci.com/rust-lang-nursery/rust-cookbook.svg?branch=master
-
-https://invalid.cc
+[build-badge]: https://github.com/rust-lang-nursery/rust-cookbook/workflows/Deploy%20to%20GitHub%20Pages/badge.svg
+[build-url]: https://github.com/rust-lang-nursery/rust-cookbook/actions?query=workflow%3A%22Deploy+to+GitHub+Pages%22
 
 **[Read it here]**.
 
@@ -32,6 +31,51 @@ $ start .\book\index.html    # windows
 $ open ./book/index.html     # mac
 ```
 
+## Development
+
+### Local Development
+
+For local development and testing, you can use the provided Makefile:
+
+```bash
+# Show all available commands
+make help
+
+# Build the book locally
+make build
+
+# Run tests
+make test
+
+# Build and test (development workflow)
+make dev
+
+# Serve the book locally with live reload
+make serve
+
+# Clean build artifacts
+make clean
+```
+
+### Deployment
+
+As a maintainer, you can deploy the site locally using:
+
+```bash
+# Deploy to GitHub Pages (requires maintainer permissions)
+make deploy
+
+# Or use the script directly
+./scripts/deploy.sh
+```
+
+The deployment script will:
+1. Build and test the book
+2. Push the built site to the `gh-pages` branch
+3. GitHub Pages will automatically serve the updated site
+
+**Note**: This requires maintainer permissions to push to the `gh-pages` branch.
+
 [Read it here]: https://rust-lang-nursery.github.io/rust-cookbook
 [Rust]: https://www.rust-lang.org/
 

scripts/deploy.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+
+set -e
+
+# Parse command line arguments
+SKIP_TESTS=false
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --skip-tests)
+            SKIP_TESTS=true
+            shift
+            ;;
+        *)
+            echo "Unknown option: $1"
+            echo "Usage: $0 [--skip-tests]"
+            exit 1
+            ;;
+    esac
+done
+
+echo "Rust Cookbook Local Deployment Script"
+echo "====================================="
+
+# Check if mdbook is installed
+if ! command -v mdbook &> /dev/null; then
+    echo "Installing mdbook..."
+    cargo install mdbook --vers "0.4.43"
+fi
+
+# Build the book
+echo "Building the book..."
+mdbook build
+
+# Copy assets
+echo "Copying assets..."
+cp -r assets/ book/
+
+# Run tests (unless --skip-tests is specified)
+if [[ "$SKIP_TESTS" == "false" ]]; then
+    echo "Running tests..."
+    cargo test
+
+    echo "Running spellcheck..."
+    ./ci/spellcheck.sh list
+else
+    echo "Skipping tests (--skip-tests flag provided)"
+fi
+
+# Check if we're on master branch
+if [[ $(git branch --show-current) != "master" ]]; then
+    echo "Warning: You're not on the master branch. Current branch: $(git branch --show-current)"
+    echo "This script is designed to deploy from the master branch."
+    read -p "Continue anyway? (y/N): " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+fi
+
+# Get current commit hash
+REV=$(git rev-parse --short HEAD)
+echo "Building for commit: $REV"
+
+# Create a temporary directory for the gh-pages branch
+TEMP_DIR=$(mktemp -d)
+echo "Using temporary directory: $TEMP_DIR"
+
+# Clone the repository to the temporary directory
+echo "Cloning repository to temporary directory..."
+git clone --depth 1 --branch gh-pages https://github.com/rust-lang-nursery/rust-cookbook.git "$TEMP_DIR" 2>/dev/null || {
+    echo "gh-pages branch doesn't exist yet, creating it..."
+    mkdir -p "$TEMP_DIR"
+    cd "$TEMP_DIR"
+    git init
+    git remote add origin https://github.com/rust-lang-nursery/rust-cookbook.git
+    cd - > /dev/null
+}
+
+# Copy the built book to the temporary directory
+echo "Copying built book to temporary directory..."
+rm -rf "$TEMP_DIR"/*
+cp -r book/* "$TEMP_DIR/"
+
+# Commit and push to gh-pages branch
+echo "Committing and pushing to gh-pages branch..."
+cd "$TEMP_DIR"
+git add -A .
+git config user.name "Rust Cookbook Maintainer"
+git config user.email "cookbook@rust-lang.org"
+git commit -m "Build cookbook at $REV" || {
+    echo "No changes to commit"
+    exit 0
+}
+
+echo "Pushing to gh-pages branch..."
+git push origin HEAD:gh-pages --force
+
+# Clean up
+cd - > /dev/null
+rm -rf "$TEMP_DIR"
+
+echo "Deployment complete!"
+echo "The site should be available at: https://rust-lang-nursery.github.io/rust-cookbook"
+echo "Note: It may take a few minutes for GitHub Pages to update." 

scripts/dev.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+set -e
+
+echo "Rust Cookbook Development Script"
+echo "================================"
+
+# Check if mdbook is installed
+if ! command -v mdbook &> /dev/null; then
+    echo "Installing mdbook..."
+    cargo install mdbook --vers "0.4.43"
+fi
+
+# Build the book
+echo "Building the book..."
+mdbook build
+
+# Copy assets
+echo "Copying assets..."
+cp -r assets/ book/
+
+# Run tests
+echo "Running tests..."
+cargo test
+
+# Run spellcheck
+echo "Running spellcheck..."
+./ci/spellcheck.sh list
+
+echo "Build complete! Open book/index.html in your browser to view the site."
+echo "Or run 'mdbook serve --open' to start a local server."