diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 00000000..ed5b8f9a --- /dev/null +++ b/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. \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..5163db38 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/README.md b/README.md index 06a79f47..9c5d10f1 100644 --- a/README.md +++ b/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/ diff --git a/scripts/deploy.sh b/scripts/deploy.sh new file mode 100755 index 00000000..19d9821a --- /dev/null +++ b/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." \ No newline at end of file diff --git a/scripts/dev.sh b/scripts/dev.sh new file mode 100755 index 00000000..4fdb5eed --- /dev/null +++ b/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." \ No newline at end of file