Skip to content

Commit a62a223

Browse files
Copilotmmcky
Copilot
and
mmcky
authored
Add comprehensive GitHub Copilot instructions for lecture-python.myst repository (#515)
* Initial plan * Add comprehensive GitHub Copilot instructions for lecture-python.myst Co-authored-by: mmcky <[email protected]> * Update file counts in copilot instructions to match actual content Co-authored-by: mmcky <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: mmcky <[email protected]>
1 parent 36bc72e commit a62a223

File tree

1 file changed

+170
-0
lines changed

1 file changed

+170
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Intermediate Quantitative Economics with Python - Lecture Materials
2+
3+
**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.**
4+
5+
## Working Effectively
6+
7+
### Bootstrap and Build the Repository
8+
Execute these commands in order to set up a complete working environment:
9+
10+
**NEVER CANCEL: Each step has specific timing expectations - wait for completion.**
11+
12+
```bash
13+
# 1. Set up conda environment (takes ~3 minutes)
14+
conda env create -f environment.yml
15+
# NEVER CANCEL: Wait 3-5 minutes for completion
16+
17+
# 2. Activate environment (required for all subsequent commands)
18+
source /usr/share/miniconda/etc/profile.d/conda.sh
19+
conda activate quantecon
20+
21+
# 3. Install PyTorch with CUDA support (takes ~3 minutes)
22+
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128
23+
# NEVER CANCEL: Wait 3-5 minutes for completion
24+
25+
# 4. Install Pyro (takes ~10 seconds)
26+
pip install pyro-ppl
27+
28+
# 5. Install JAX with CUDA support (takes ~30 seconds)
29+
pip install --upgrade "jax[cuda12-local]==0.6.2"
30+
31+
# 6. Install NumPyro (takes ~5 seconds)
32+
pip install numpyro
33+
34+
# 7. Test JAX installation (takes ~5 seconds)
35+
python scripts/test-jax-install.py
36+
```
37+
38+
### Build Commands
39+
40+
**CRITICAL TIMING WARNING: NEVER CANCEL BUILD COMMANDS - They take 45+ minutes to complete.**
41+
42+
```bash
43+
# HTML build (primary build target) - takes 45-60 minutes
44+
jb build lectures --path-output ./ -W --keep-going
45+
# NEVER CANCEL: Set timeout to 90+ minutes. Executes 80+ notebooks sequentially.
46+
47+
# PDF build via LaTeX - takes 30-45 minutes
48+
jb build lectures --builder pdflatex --path-output ./ -n -W --keep-going
49+
# NEVER CANCEL: Set timeout to 75+ minutes.
50+
51+
# Jupyter notebook build - takes 30-45 minutes
52+
jb build lectures --path-output ./ --builder=custom --custom-builder=jupyter -n -W --keep-going
53+
# NEVER CANCEL: Set timeout to 75+ minutes.
54+
```
55+
56+
### Environment and Dependency Details
57+
58+
- **Python**: 3.12 with Anaconda 2024.10
59+
- **Primary Framework**: Jupyter Book 1.0.3 with MyST markdown
60+
- **Scientific Computing**: JAX 0.6.2, PyTorch (nightly), NumPyro, SciPy
61+
- **Content Format**: MyST markdown files in `/lectures/` directory
62+
- **Build System**: Sphinx-based via Jupyter Book
63+
- **Execution**: Notebooks are executed during build and cached
64+
65+
### Validation Scenarios
66+
67+
**Always run these validation steps after making changes:**
68+
69+
1. **Environment Test**: `python scripts/test-jax-install.py` - verifies JAX/scientific stack
70+
2. **Build Test**: Start HTML build and verify first few notebooks execute successfully
71+
3. **Content Verification**: Check `_build/html/` directory contains expected output files
72+
4. **Notebook Validation**: Verify generated notebooks in `_build/jupyter/` are executable
73+
74+
### Known Limitations and Workarounds
75+
76+
- **Network Access**: Intersphinx inventory warnings for external sites (intro.quantecon.org, python-advanced.quantecon.org) are expected in sandboxed environments - build continues normally
77+
- **GPU Support**: JAX runs in CPU mode in most environments - this is expected and functional
78+
- **Build Cache**: Uses `_build/.jupyter_cache` to avoid re-executing unchanged notebooks
79+
- **Memory Usage**: Large notebooks may require substantial RAM during execution phase
80+
81+
## Project Architecture
82+
83+
### Key Directories
84+
```
85+
lectures/ # MyST markdown lecture files (80+ files)
86+
├── _config.yml # Jupyter Book configuration
87+
├── _toc.yml # Table of contents structure
88+
├── _static/ # Static assets (images, CSS, etc.)
89+
└── *.md # Individual lecture files
90+
91+
_build/ # Build outputs (created during build)
92+
├── html/ # HTML website output
93+
├── latex/ # PDF build intermediate files
94+
├── jupyter/ # Generated notebook files
95+
└── .jupyter_cache/ # Execution cache
96+
97+
scripts/ # Utility scripts
98+
└── test-jax-install.py # JAX installation validator
99+
100+
.github/ # CI/CD workflows
101+
└── workflows/ # GitHub Actions definitions
102+
```
103+
104+
### Content Structure
105+
- **80+ lecture files** covering intermediate quantitative economics
106+
- **MyST markdown format** with embedded Python code blocks
107+
- **Executable notebooks** - code is run during build process
108+
- **Multiple output formats**: HTML website, PDF via LaTeX, downloadable notebooks
109+
110+
### Build Targets
111+
1. **HTML**: Main website at `_build/html/` - primary deliverable
112+
2. **PDF**: Single PDF document via LaTeX at `_build/latex/`
113+
3. **Notebooks**: Individual .ipynb files at `_build/jupyter/`
114+
115+
## Development Workflow
116+
117+
### Making Changes
118+
1. **Always activate environment first**: `conda activate quantecon`
119+
2. **Edit lecture files**: Modify `.md` files in `/lectures/` directory
120+
3. **Test changes**: Run quick build test on subset if possible
121+
4. **Full validation**: Complete HTML build to verify all notebooks execute
122+
5. **Check outputs**: Verify `_build/html/` contains expected results
123+
124+
### Common Tasks
125+
126+
**View repository structure:**
127+
```bash
128+
ls -la /home/runner/work/lecture-python.myst/lecture-python.myst/
129+
# Output: .git .github .gitignore README.md _notebook_repo environment.yml lectures scripts
130+
```
131+
132+
**Check lecture content:**
133+
```bash
134+
ls lectures/ | head -10
135+
# Shows: intro.md, various economics topic files (.md format)
136+
```
137+
138+
**Monitor build progress:**
139+
- Build shows progress as "reading sources... [X%] filename"
140+
- Each notebook execution time varies: 5-120 seconds per file
141+
- Total build time: 45-60 minutes for full HTML build
142+
143+
**Environment verification:**
144+
```bash
145+
conda list | grep -E "(jax|torch|jupyter-book)"
146+
# Should show: jax 0.6.2, torch 2.9.0.dev, jupyter-book 1.0.3
147+
```
148+
149+
## Troubleshooting
150+
151+
### Common Issues
152+
- **"cuInit(0) failed"**: Expected JAX warning in CPU-only environments - build continues normally
153+
- **Intersphinx warnings**: Network inventory fetch failures are expected - build continues normally
154+
- **Debugger warnings**: "frozen modules" warnings during notebook execution are normal
155+
- **Long execution times**: Some notebooks (like ar1_bayes.md) take 60+ seconds - this is normal
156+
157+
### Performance Notes
158+
- **First build**: Takes longest due to fresh notebook execution
159+
- **Subsequent builds**: Faster due to caching system
160+
- **Cache location**: `_build/.jupyter_cache` stores execution results
161+
- **Cache invalidation**: Changes to notebook content triggers re-execution
162+
163+
## CI/CD Integration
164+
165+
The repository uses GitHub Actions with:
166+
- **Cache workflow**: Weekly rebuild of execution cache
167+
- **CI workflow**: Pull request validation builds
168+
- **Publish workflow**: Production deployment on tags
169+
170+
**Local builds should match CI behavior** - use same commands and expect similar timing.

0 commit comments

Comments
 (0)