From 23cfbee1cce9bbe5001f6facb8b2fed31a96a145 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Tue, 12 Aug 2025 00:31:21 +0000 Subject: [PATCH 1/3] Initial plan From 364de7d63980ee6bb29d1afafe970b2912630d34 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 12 Aug 2025 01:06:31 +0000 Subject: [PATCH 2/3] Add comprehensive GitHub Copilot instructions for Jupyter Book development Co-authored-by: mmcky <8263752+mmcky@users.noreply.github.com> --- .github/copilot-instructions.md | 113 ++++++++++++++++++++++++++++++++ lectures/foo.py | 2 + lectures/newfile.txt | 2 + lectures/numbers.txt | 6 ++ lectures/output.txt | 3 + lectures/output2.txt | 5 ++ lectures/test_table.csv | 11 ++++ lectures/us_cities.txt | 9 +++ 8 files changed, 151 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 lectures/foo.py create mode 100644 lectures/newfile.txt create mode 100644 lectures/numbers.txt create mode 100644 lectures/output.txt create mode 100644 lectures/output2.txt create mode 100644 lectures/test_table.csv create mode 100644 lectures/us_cities.txt diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..c244fbe4 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,113 @@ +# Python Programming for Economics and Finance - Lecture Series + +This repository contains QuantEcon's Python Programming lecture series built using Jupyter Book. The lectures are written in MyST Markdown format and compiled into HTML, PDF, and Jupyter notebook formats. + +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. + +## Working Effectively + +### Environment Setup +- **NEVER CANCEL**: Environment creation takes 3+ minutes. Set timeout to 5+ minutes. +- Create conda environment: `conda env create -f environment.yml` +- Activate environment: `eval "$(conda shell.bash hook)" && conda activate quantecon` +- **CRITICAL**: Always activate the quantecon environment before running any jb commands. + +### Building the Site +- **NEVER CANCEL**: HTML builds take 4+ minutes. Set timeout to 8+ minutes. +- Build HTML: `jb build lectures --path-output ./ -n -W --keep-going` +- **NEVER CANCEL**: LaTeX dependency installation takes 20+ minutes. Set timeout to 35+ minutes. +- Install LaTeX dependencies: `sudo apt-get update -qq && sudo apt-get install -y texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra texlive-xetex latexmk xindy dvipng cm-super` +- Build PDF LaTeX: `jb build lectures --builder pdflatex --path-output ./ -n -W --keep-going` -- takes 1 minute. Set timeout to 2+ minutes. +- Build Jupyter notebooks: `jb build lectures --path-output ./ --builder=custom --custom-builder=jupyter -n -W --keep-going` -- takes 1 minute. Set timeout to 2+ minutes. + +### Compilation Notes +- HTML build always succeeds but returns exit code 1 due to warnings (jax.quantecon.org unreachable) - this is normal. +- PDF compilation using `latexmk -pdf -silent quantecon-python-programming.tex` in `_build/latex/` produces a PDF but has reference warnings - this is normal. +- Jupyter notebook generation works reliably and is cached for subsequent builds. + +### Cleaning +- Clean all builds: `jb clean lectures --all` +- Remove build directory: `rm -rf _build` + +## Validation +- **ALWAYS run these validation steps** after making changes to ensure functionality. +- Start local server: `python -m http.server 8000 --directory _build/html` +- Verify site loads: Navigate to `http://localhost:8000` and confirm the table of contents displays correctly. +- **MANUAL VALIDATION REQUIREMENT**: Always test navigation by clicking through at least 3 lecture links to verify content renders properly. +- Check output files exist: + - HTML: `ls -la _build/html/*.html | head -5` + - Notebooks: `ls -la _build/jupyter/*.ipynb | head -5` + - PDF: `ls -la _build/latex/*.pdf` +- **Always validate image rendering** by checking a lecture with plots (e.g., matplotlib or numpy lectures). + +### Linting and Code Quality +- Use pylint for Python code validation: `pylint [file]` +- **Always check MyST syntax** by ensuring the build completes without MyST parsing errors. +- The build process includes automatic syntax validation - failed MyST parsing will stop the build. + +## Repository Structure + +### Key Directories +- `/lectures/` - Contains all MyST Markdown lecture files +- `/lectures/_config.yml` - Jupyter Book configuration +- `/lectures/_toc.yml` - Table of contents structure +- `/_build/html/` - Generated HTML website +- `/_build/latex/` - Generated LaTeX/PDF files +- `/_build/jupyter/` - Generated Jupyter notebooks +- `/.github/workflows/` - CI/CD pipelines + +### Important Files +- `environment.yml` - Conda environment specification (Python 3.13 + Anaconda + Jupyter Book stack) +- `README.md` - Repository documentation +- `.gitignore` - Excludes `_build/` and other build artifacts + +## Common Tasks + +### Adding New Lectures +1. Create new `.md` file in `/lectures/` directory using MyST format +2. Add entry to `/lectures/_toc.yml` in appropriate section +3. Build and validate: Follow full build and validation process above +4. **Always test** the new lecture loads correctly in the web interface + +### Modifying Existing Lectures +1. Edit the `.md` file in `/lectures/` directory +2. Build HTML to test changes: `jb build lectures --path-output ./ -n -W --keep-going` +3. **Always validate** the specific lecture page loads and renders correctly +4. Check for broken internal links or references + +### Updating Dependencies +1. Modify `environment.yml` for conda packages +2. Recreate environment: `conda env remove -n quantecon && conda env create -f environment.yml` +3. **NEVER CANCEL**: Full environment recreation takes 3+ minutes +4. **Always test** full build process after dependency changes + +## Troubleshooting + +### Common Issues +- **"jax.quantecon.org unreachable"**: This warning is expected due to network restrictions. Build continues normally. +- **PDF reference warnings**: LaTeX compilation produces warnings about undefined references but still generates a usable PDF. +- **Exit code 1 with warnings**: HTML builds return non-zero exit codes due to warnings but produce valid output. +- **MyST parsing errors**: Check MyST syntax in affected `.md` files. Common issues: incorrect code block syntax, malformed cross-references. + +### Build Failures +- **Clean and rebuild**: `rm -rf _build && jb build lectures --path-output ./ -n -W --keep-going` +- **Check conda environment**: Ensure quantecon environment is active before running jb commands +- **LaTeX issues**: Verify LaTeX dependencies are installed if PDF compilation fails + +### Performance Notes +- **First build**: Takes 4+ minutes due to notebook execution and image generation +- **Subsequent builds**: Use Jupyter cache, typically complete in similar time +- **PDF compilation**: Fast (~30 seconds) but may have reference issues +- **Memory usage**: Large builds may require sufficient RAM for image processing + +## Expected Timing +Reference these timing expectations when setting appropriate timeouts: + +- Environment creation: 3 minutes (set timeout: 5+ minutes) +- LaTeX dependencies: 20+ minutes (set timeout: 35+ minutes) +- HTML build: 4-5 minutes (set timeout: 8+ minutes) +- PDF LaTeX build: 30 seconds (set timeout: 2+ minutes) +- Jupyter build: 45 seconds (set timeout: 2+ minutes) +- PDF compilation: 30 seconds (set timeout: 2+ minutes) + +**NEVER CANCEL long-running operations** - they are expected to take significant time. \ No newline at end of file diff --git a/lectures/foo.py b/lectures/foo.py new file mode 100644 index 00000000..14cce625 --- /dev/null +++ b/lectures/foo.py @@ -0,0 +1,2 @@ + +print("foobar") diff --git a/lectures/newfile.txt b/lectures/newfile.txt new file mode 100644 index 00000000..119fdd30 --- /dev/null +++ b/lectures/newfile.txt @@ -0,0 +1,2 @@ +Testing +Testing again \ No newline at end of file diff --git a/lectures/numbers.txt b/lectures/numbers.txt new file mode 100644 index 00000000..5a6193d8 --- /dev/null +++ b/lectures/numbers.txt @@ -0,0 +1,6 @@ +prices +3 +8 + +7 +21 diff --git a/lectures/output.txt b/lectures/output.txt new file mode 100644 index 00000000..66a30a78 --- /dev/null +++ b/lectures/output.txt @@ -0,0 +1,3 @@ +Line 0: Testing + +Line 1: Testing again diff --git a/lectures/output2.txt b/lectures/output2.txt new file mode 100644 index 00000000..7696e417 --- /dev/null +++ b/lectures/output2.txt @@ -0,0 +1,5 @@ +Line 0: Testing + +Line 1: Testing again + +This is the end of the file \ No newline at end of file diff --git a/lectures/test_table.csv b/lectures/test_table.csv new file mode 100644 index 00000000..03fcd0fb --- /dev/null +++ b/lectures/test_table.csv @@ -0,0 +1,11 @@ +Date,Open,High,Low,Close,Volume,Adj Close +2009-05-21,9280.35,9286.35,9189.92,9264.15,133200,9264.15 +2009-05-20,9372.72,9399.40,9311.61,9344.64,143200,9344.64 +2009-05-19,9172.56,9326.75,9166.97,9290.29,167000,9290.29 +2009-05-18,9167.05,9167.82,8997.74,9038.69,147800,9038.69 +2009-05-15,9150.21,9272.08,9140.90,9265.02,172000,9265.02 +2009-05-14,9212.30,9223.77,9052.41,9093.73,169400,9093.73 +2009-05-13,9305.79,9379.47,9278.89,9340.49,176000,9340.49 +2009-05-12,9358.25,9389.61,9298.61,9298.61,188400,9298.61 +2009-05-11,9460.72,9503.91,9342.75,9451.98,230800,9451.98 +2009-05-08,9351.40,9464.43,9349.57,9432.83,220200,9432.83 diff --git a/lectures/us_cities.txt b/lectures/us_cities.txt new file mode 100644 index 00000000..9be9260f --- /dev/null +++ b/lectures/us_cities.txt @@ -0,0 +1,9 @@ +new york: 8244910 +los angeles: 3819702 +chicago: 2707120 +houston: 2145146 +philadelphia: 1536471 +phoenix: 1469471 +san antonio: 1359758 +san diego: 1326179 +dallas: 1223229 From c760835ba937f7846a6c430b5e4e261c3e0ef1d8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 12 Aug 2025 01:07:47 +0000 Subject: [PATCH 3/3] Clean up test files and improve gitignore patterns Co-authored-by: mmcky <8263752+mmcky@users.noreply.github.com> --- .gitignore | 5 ++++- lectures/foo.py | 2 -- lectures/newfile.txt | 2 -- lectures/numbers.txt | 6 ------ lectures/output.txt | 3 --- lectures/output2.txt | 5 ----- lectures/test_table.csv | 11 ----------- lectures/us_cities.txt | 9 --------- 8 files changed, 4 insertions(+), 39 deletions(-) delete mode 100644 lectures/foo.py delete mode 100644 lectures/newfile.txt delete mode 100644 lectures/numbers.txt delete mode 100644 lectures/output.txt delete mode 100644 lectures/output2.txt delete mode 100644 lectures/test_table.csv delete mode 100644 lectures/us_cities.txt diff --git a/.gitignore b/.gitignore index a15f5193..d8655893 100644 --- a/.gitignore +++ b/.gitignore @@ -10,4 +10,7 @@ dask-worker-space lectures/sine_wave.py lectures/mathfoo.py lectures/mod.py -lectures/test.py \ No newline at end of file +lectures/test.py +lectures/foo.py +lectures/*.txt +lectures/*.csv \ No newline at end of file diff --git a/lectures/foo.py b/lectures/foo.py deleted file mode 100644 index 14cce625..00000000 --- a/lectures/foo.py +++ /dev/null @@ -1,2 +0,0 @@ - -print("foobar") diff --git a/lectures/newfile.txt b/lectures/newfile.txt deleted file mode 100644 index 119fdd30..00000000 --- a/lectures/newfile.txt +++ /dev/null @@ -1,2 +0,0 @@ -Testing -Testing again \ No newline at end of file diff --git a/lectures/numbers.txt b/lectures/numbers.txt deleted file mode 100644 index 5a6193d8..00000000 --- a/lectures/numbers.txt +++ /dev/null @@ -1,6 +0,0 @@ -prices -3 -8 - -7 -21 diff --git a/lectures/output.txt b/lectures/output.txt deleted file mode 100644 index 66a30a78..00000000 --- a/lectures/output.txt +++ /dev/null @@ -1,3 +0,0 @@ -Line 0: Testing - -Line 1: Testing again diff --git a/lectures/output2.txt b/lectures/output2.txt deleted file mode 100644 index 7696e417..00000000 --- a/lectures/output2.txt +++ /dev/null @@ -1,5 +0,0 @@ -Line 0: Testing - -Line 1: Testing again - -This is the end of the file \ No newline at end of file diff --git a/lectures/test_table.csv b/lectures/test_table.csv deleted file mode 100644 index 03fcd0fb..00000000 --- a/lectures/test_table.csv +++ /dev/null @@ -1,11 +0,0 @@ -Date,Open,High,Low,Close,Volume,Adj Close -2009-05-21,9280.35,9286.35,9189.92,9264.15,133200,9264.15 -2009-05-20,9372.72,9399.40,9311.61,9344.64,143200,9344.64 -2009-05-19,9172.56,9326.75,9166.97,9290.29,167000,9290.29 -2009-05-18,9167.05,9167.82,8997.74,9038.69,147800,9038.69 -2009-05-15,9150.21,9272.08,9140.90,9265.02,172000,9265.02 -2009-05-14,9212.30,9223.77,9052.41,9093.73,169400,9093.73 -2009-05-13,9305.79,9379.47,9278.89,9340.49,176000,9340.49 -2009-05-12,9358.25,9389.61,9298.61,9298.61,188400,9298.61 -2009-05-11,9460.72,9503.91,9342.75,9451.98,230800,9451.98 -2009-05-08,9351.40,9464.43,9349.57,9432.83,220200,9432.83 diff --git a/lectures/us_cities.txt b/lectures/us_cities.txt deleted file mode 100644 index 9be9260f..00000000 --- a/lectures/us_cities.txt +++ /dev/null @@ -1,9 +0,0 @@ -new york: 8244910 -los angeles: 3819702 -chicago: 2707120 -houston: 2145146 -philadelphia: 1536471 -phoenix: 1469471 -san antonio: 1359758 -san diego: 1326179 -dallas: 1223229