Skip to content

Commit aef6fd5

Browse files
Copilotmmcky
Copilot
and
mmcky
authored
Add comprehensive GitHub Copilot instructions for Jupyter Book development workflow (#382)
* Initial plan * Add comprehensive GitHub Copilot instructions for Jupyter Book development Co-authored-by: mmcky <[email protected]> * Clean up test files and improve gitignore patterns Co-authored-by: mmcky <[email protected]> --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: mmcky <[email protected]>
1 parent ed9fabe commit aef6fd5

File tree

2 files changed

+117
-1
lines changed

2 files changed

+117
-1
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Python Programming for Economics and Finance - Lecture Series
2+
3+
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.
4+
5+
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.
6+
7+
## Working Effectively
8+
9+
### Environment Setup
10+
- **NEVER CANCEL**: Environment creation takes 3+ minutes. Set timeout to 5+ minutes.
11+
- Create conda environment: `conda env create -f environment.yml`
12+
- Activate environment: `eval "$(conda shell.bash hook)" && conda activate quantecon`
13+
- **CRITICAL**: Always activate the quantecon environment before running any jb commands.
14+
15+
### Building the Site
16+
- **NEVER CANCEL**: HTML builds take 4+ minutes. Set timeout to 8+ minutes.
17+
- Build HTML: `jb build lectures --path-output ./ -n -W --keep-going`
18+
- **NEVER CANCEL**: LaTeX dependency installation takes 20+ minutes. Set timeout to 35+ minutes.
19+
- 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`
20+
- Build PDF LaTeX: `jb build lectures --builder pdflatex --path-output ./ -n -W --keep-going` -- takes 1 minute. Set timeout to 2+ minutes.
21+
- 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.
22+
23+
### Compilation Notes
24+
- HTML build always succeeds but returns exit code 1 due to warnings (jax.quantecon.org unreachable) - this is normal.
25+
- PDF compilation using `latexmk -pdf -silent quantecon-python-programming.tex` in `_build/latex/` produces a PDF but has reference warnings - this is normal.
26+
- Jupyter notebook generation works reliably and is cached for subsequent builds.
27+
28+
### Cleaning
29+
- Clean all builds: `jb clean lectures --all`
30+
- Remove build directory: `rm -rf _build`
31+
32+
## Validation
33+
- **ALWAYS run these validation steps** after making changes to ensure functionality.
34+
- Start local server: `python -m http.server 8000 --directory _build/html`
35+
- Verify site loads: Navigate to `http://localhost:8000` and confirm the table of contents displays correctly.
36+
- **MANUAL VALIDATION REQUIREMENT**: Always test navigation by clicking through at least 3 lecture links to verify content renders properly.
37+
- Check output files exist:
38+
- HTML: `ls -la _build/html/*.html | head -5`
39+
- Notebooks: `ls -la _build/jupyter/*.ipynb | head -5`
40+
- PDF: `ls -la _build/latex/*.pdf`
41+
- **Always validate image rendering** by checking a lecture with plots (e.g., matplotlib or numpy lectures).
42+
43+
### Linting and Code Quality
44+
- Use pylint for Python code validation: `pylint [file]`
45+
- **Always check MyST syntax** by ensuring the build completes without MyST parsing errors.
46+
- The build process includes automatic syntax validation - failed MyST parsing will stop the build.
47+
48+
## Repository Structure
49+
50+
### Key Directories
51+
- `/lectures/` - Contains all MyST Markdown lecture files
52+
- `/lectures/_config.yml` - Jupyter Book configuration
53+
- `/lectures/_toc.yml` - Table of contents structure
54+
- `/_build/html/` - Generated HTML website
55+
- `/_build/latex/` - Generated LaTeX/PDF files
56+
- `/_build/jupyter/` - Generated Jupyter notebooks
57+
- `/.github/workflows/` - CI/CD pipelines
58+
59+
### Important Files
60+
- `environment.yml` - Conda environment specification (Python 3.13 + Anaconda + Jupyter Book stack)
61+
- `README.md` - Repository documentation
62+
- `.gitignore` - Excludes `_build/` and other build artifacts
63+
64+
## Common Tasks
65+
66+
### Adding New Lectures
67+
1. Create new `.md` file in `/lectures/` directory using MyST format
68+
2. Add entry to `/lectures/_toc.yml` in appropriate section
69+
3. Build and validate: Follow full build and validation process above
70+
4. **Always test** the new lecture loads correctly in the web interface
71+
72+
### Modifying Existing Lectures
73+
1. Edit the `.md` file in `/lectures/` directory
74+
2. Build HTML to test changes: `jb build lectures --path-output ./ -n -W --keep-going`
75+
3. **Always validate** the specific lecture page loads and renders correctly
76+
4. Check for broken internal links or references
77+
78+
### Updating Dependencies
79+
1. Modify `environment.yml` for conda packages
80+
2. Recreate environment: `conda env remove -n quantecon && conda env create -f environment.yml`
81+
3. **NEVER CANCEL**: Full environment recreation takes 3+ minutes
82+
4. **Always test** full build process after dependency changes
83+
84+
## Troubleshooting
85+
86+
### Common Issues
87+
- **"jax.quantecon.org unreachable"**: This warning is expected due to network restrictions. Build continues normally.
88+
- **PDF reference warnings**: LaTeX compilation produces warnings about undefined references but still generates a usable PDF.
89+
- **Exit code 1 with warnings**: HTML builds return non-zero exit codes due to warnings but produce valid output.
90+
- **MyST parsing errors**: Check MyST syntax in affected `.md` files. Common issues: incorrect code block syntax, malformed cross-references.
91+
92+
### Build Failures
93+
- **Clean and rebuild**: `rm -rf _build && jb build lectures --path-output ./ -n -W --keep-going`
94+
- **Check conda environment**: Ensure quantecon environment is active before running jb commands
95+
- **LaTeX issues**: Verify LaTeX dependencies are installed if PDF compilation fails
96+
97+
### Performance Notes
98+
- **First build**: Takes 4+ minutes due to notebook execution and image generation
99+
- **Subsequent builds**: Use Jupyter cache, typically complete in similar time
100+
- **PDF compilation**: Fast (~30 seconds) but may have reference issues
101+
- **Memory usage**: Large builds may require sufficient RAM for image processing
102+
103+
## Expected Timing
104+
Reference these timing expectations when setting appropriate timeouts:
105+
106+
- Environment creation: 3 minutes (set timeout: 5+ minutes)
107+
- LaTeX dependencies: 20+ minutes (set timeout: 35+ minutes)
108+
- HTML build: 4-5 minutes (set timeout: 8+ minutes)
109+
- PDF LaTeX build: 30 seconds (set timeout: 2+ minutes)
110+
- Jupyter build: 45 seconds (set timeout: 2+ minutes)
111+
- PDF compilation: 30 seconds (set timeout: 2+ minutes)
112+
113+
**NEVER CANCEL long-running operations** - they are expected to take significant time.

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,7 @@ dask-worker-space
1010
lectures/sine_wave.py
1111
lectures/mathfoo.py
1212
lectures/mod.py
13-
lectures/test.py
13+
lectures/test.py
14+
lectures/foo.py
15+
lectures/*.txt
16+
lectures/*.csv

0 commit comments

Comments
 (0)