From 411f0afe204ab8d8794ee1180a0e9a59f1b509de Mon Sep 17 00:00:00 2001 From: mmcky Date: Mon, 20 Oct 2025 11:17:07 +1100 Subject: [PATCH] Clarify README with deployment and contribution workflow - Add clear GitHub Pages deployment section with custom domain setup - Explain interactive.quantecon.org configuration - Clarify content management workflow (direct edits vs sync script) - Remove confusing cross-repository requirements - Add standard PR workflow for contributors - Improve structure and readability - Add troubleshooting section --- README.md | 201 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 178 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 5b13456..99778ce 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,198 @@ -# QuantEcon WASM project +# QuantEcon WASM Project -This repository contains a subset of the [lecture-python-intro](https://intro.quantecon.org/intro.html). +This repository contains the WASM-enabled version of [QuantEcon's Introduction to Quantitative Economics with Python](https://intro.quantecon.org/intro.html) lecture series. -This project is powered by Pyodide kernel which allows us to run the lectures in the browser without -any installation. +**Live Site**: [interactive.quantecon.org](https://interactive.quantecon.org) -## Development +This project uses **Pyodide** to run Python code directly in the browser, allowing users to interact with lectures without any local installation. -The script `update_lectures.py` is used to fetch the latest version of lectures from the -[wasm branch of lecture-python-intro series](https://github.com/QuantEcon/lecture-python-intro/tree/wasm). +## Overview -In order to build and test the project locally, please install the required libraries using -``` +- **Source Content**: Synchronized from the [`wasm` branch of lecture-python-intro](https://github.com/QuantEcon/lecture-python-intro/tree/wasm) +- **Build System**: TeachBooks (built on Jupyter Book) +- **Execution**: Pyodide (Python + scientific stack in WebAssembly) +- **Hosting**: GitHub Pages +- **Domain**: interactive.quantecon.org + +## Quick Start + +### Prerequisites + +- Python 3.11 or later +- pip + +### Installation + +```bash +# Clone the repository +git clone https://github.com/QuantEcon/project.lecture-wasm.git +cd project.lecture-wasm + +# Install dependencies pip install -r requirements.txt ``` -The first step is to build the lecture series. To do so, use the following: -``` +### Build and Serve Locally + +```bash +# Build the book teachbooks build book -``` -And run a local server using -``` +# Serve locally (default: http://localhost:8000) teachbooks serve + +# Stop the server +teachbooks serve stop ``` -To stop the server use: +## Content Management + +### Editing Lectures in This Repository + +**For most edits**, you can work directly in this repository using the standard GitHub workflow: + +1. Create a feature branch: `git checkout -b fix/my-edit` +2. Make your changes to files in `book/` (e.g., `book/long_run_growth.md`) +3. Build and test locally: `teachbooks build book` +4. Commit and push: `git push origin fix/my-edit` +5. Open a Pull Request to merge into `main` +6. Once merged, changes automatically deploy to interactive.quantecon.org + +### Synchronizing from Source Repository + +This repository mirrors content from the [`wasm` branch of lecture-python-intro](https://github.com/QuantEcon/lecture-python-intro/tree/wasm). The `wasm` branch contains WASM-compatible versions of lectures that exist in the main QuantEcon lecture series. + +**When to sync**: Run this when upstream lectures are updated in the source repository: + +```bash +python update_lectures.py ``` -teachbooks serve stop + +This script: +- Downloads the latest lectures from the `wasm` branch of `lecture-python-intro` +- Transforms `!pip install` to `%pip install` (WASM-compatible) +- Updates lecture files in the `book/` directory + +**Note**: Most contributors should edit files directly in this repo. The sync script is mainly used by maintainers to pull in updates from the broader QuantEcon lecture series. + +## Deployment + +### GitHub Pages Deployment + +The site is automatically deployed to GitHub Pages when changes are pushed to the `main` branch. + +#### Deployment Workflow + +1. **Push to main**: Commits trigger the deployment workflow +2. **Build**: GitHub Actions builds the book using TeachBooks +3. **Deploy**: Static HTML is deployed to the `gh-pages` branch +4. **Live**: Changes appear at interactive.quantecon.org + +#### Manual Deployment + +To trigger a deployment manually: + +1. Go to the **Actions** tab on GitHub +2. Select the **Build and Deploy** workflow +3. Click **Run workflow** → Select `main` branch → **Run** + +#### Custom Domain Setup + +The site is configured to use **interactive.quantecon.org**: + +1. **DNS Configuration**: CNAME record pointing to `quantecon.github.io` +2. **Repository Settings**: + - Settings → Pages + - Custom domain: `interactive.quantecon.org` + - Enforce HTTPS: ✓ Enabled +3. **CNAME file**: Automatically maintained in `gh-pages` branch + +#### Deployment Files + +- `.github/workflows/deploy.yml` - Production deployment workflow +- `.github/workflows/ci_pr.yml` - PR preview deployment (Netlify) + +## Project Structure + +``` +project.lecture-wasm/ +├── book/ # Lecture content +│ ├── _config.yml # Book configuration +│ ├── _toc.yml # Table of contents +│ ├── *.md # Lecture files (MyST markdown) +│ ├── _static/ # Static assets (CSS, bibliography) +│ ├── datasets/ # Data files +│ └── figures/ # Images +├── .github/ +│ └── workflows/ # CI/CD workflows +├── requirements.txt # Python dependencies +├── update_lectures.py # Content sync script +└── README.md # This file ``` -### Update a lecture? +## Technology Stack + +- **TeachBooks**: Static site generator (extends Jupyter Book) +- **Pyodide**: WebAssembly Python runtime +- **MyST Markdown**: Enhanced markdown for technical content +- **Sphinx**: Documentation engine +- **Thebe-lite**: Browser-based code execution + +## Contributing + +We welcome contributions! Here's the standard workflow: + +1. **Fork** this repository +2. **Create a branch**: `git checkout -b feature/my-improvement` +3. **Make changes** to files in `book/` directory +4. **Test locally**: + ```bash + teachbooks build book + teachbooks serve + ``` +5. **Commit**: `git commit -m "Description of changes"` +6. **Push**: `git push origin feature/my-improvement` +7. **Open a Pull Request** to merge into `main` + +Once your PR is merged, GitHub Actions will automatically deploy the changes to interactive.quantecon.org. -In order to update any lecture, it's recommended to update the same lecture in the -[wasm branch of lecture-python-intro series](https://github.com/QuantEcon/lecture-python-intro/tree/wasm) and -run the script +## Troubleshooting + +### Build Errors + +```bash +# Clean build +rm -rf book/_build +teachbooks build book ``` -python update_lectures.py + +### Port Already in Use + +```bash +# Use a different port +teachbooks serve --port 8080 +``` + +### Package Installation Issues + +```bash +# Update pip and reinstall +pip install --upgrade pip +pip install -r requirements.txt --force-reinstall ``` -This allows us the keep all the lectures up-to-date in a single place and keep this repository a mirror of the -main repository. +## License + +This project is licensed under the **Creative Commons Attribution 4.0 International License (CC BY 4.0)**. See [LICENSE](LICENSE) for details. + +## Authors + +- **Thomas J. Sargent** - http://www.tomsargent.com/ +- **John Stachurski** - https://johnstachurski.net/ + +## Links + +- **Live Site**: https://interactive.quantecon.org +- **Source Lectures**: https://github.com/QuantEcon/lecture-python-intro/tree/wasm +- **QuantEcon**: https://quantecon.org/ +- **Pyodide**: https://pyodide.org/