├── README.md ├── FUNDING.yml ├── lectures └── README.md ├── environment.yml └── .github ├── dependabot.yml ├── workflows ├── quantecon-env-osx.yml ├── quantecon-env-linux.yml └── quantecon-env-win.yml └── copilot-instructions.md /README.md: -------------------------------------------------------------------------------- 1 | # .github 2 | 3 | Templates and Common Organisation Files 4 | -------------------------------------------------------------------------------- /FUNDING.yml: -------------------------------------------------------------------------------- 1 | github: numfocus 2 | custom: https://numfocus.org/donate-to-quantecon -------------------------------------------------------------------------------- /lectures/README.md: -------------------------------------------------------------------------------- 1 | # { lecture title } 2 | 3 | { lecture description } 4 | 5 | ## Jupyter notebooks 6 | 7 | Jupyter notebook versions of each lecture are available for download 8 | via the website. 9 | 10 | ## Contributions 11 | 12 | To comment on the lectures please add to or open an issue in the issue tracker (see above). 13 | 14 | We welcome pull requests! 15 | 16 | Please read the [QuantEcon style guide](https://manual.quantecon.org/intro.html) first, so that you can match our style. -------------------------------------------------------------------------------- /environment.yml: -------------------------------------------------------------------------------- 1 | name: quantecon 2 | channels: 3 | - default 4 | dependencies: 5 | - python=3.13 6 | - anaconda=2025.06 7 | - pip 8 | - pip: 9 | - jupyter-book==1.0.4post1 10 | - quantecon-book-theme==0.8.3 11 | - sphinx-tojupyter==0.3.1 12 | - sphinxext-rediraffe==0.2.7 13 | - sphinx-reredirects==1.0.0 14 | - sphinx-exercise==1.0.1 15 | - sphinx-proof==0.2.1 16 | - sphinxcontrib-youtube==1.4.1 17 | - sphinx-togglebutton==0.3.2 18 | # Author Requirements 19 | - jupyterlab-myst 20 | - jupytext 21 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # To get started with Dependabot version updates, you'll need to specify which 2 | # package ecosystems to update and where the package manifests are located. 3 | # Please see the documentation for all configuration options: 4 | # https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file 5 | 6 | version: 2 7 | updates: 8 | - package-ecosystem: github-actions 9 | directory: / 10 | commit-message: 11 | prefix: ⬆️ 12 | schedule: 13 | interval: weekly 14 | -------------------------------------------------------------------------------- /.github/workflows/quantecon-env-osx.yml: -------------------------------------------------------------------------------- 1 | name: Test QuantEcon Environment (OS X) 2 | on: 3 | schedule: 4 | # UTC 22:00 is early morning in Australia on Monday 5 | - cron: '0 22 * * 1' 6 | push: 7 | branches: 8 | - main 9 | jobs: 10 | execution-tests-osx: 11 | name: Execution Tests (${{ matrix.python-version }}, ${{ matrix.os }}) 12 | runs-on: ${{ matrix.os }} 13 | strategy: 14 | fail-fast: false 15 | matrix: 16 | os: ["macos-latest"] 17 | python-version: ["3.9"] 18 | steps: 19 | - name: Checkout 20 | uses: actions/checkout@v5 21 | - uses: conda-incubator/setup-miniconda@v3 22 | with: 23 | auto-update-conda: true 24 | auto-activate-base: true 25 | miniconda-version: 'latest' 26 | python-version: ${{ matrix.python-version }} 27 | environment-file: environment.yml 28 | activate-environment: quantecon 29 | - name: Build lecture-python-programming 30 | shell: bash -l {0} 31 | run: | 32 | git clone https://github.com/quantecon/lecture-python-programming.myst 33 | cd lecture-python-programming.myst 34 | jb build lectures -W --keep-going 35 | - name: Upload Execution Reports (lecture-python-programming) 36 | uses: actions/upload-artifact@v4 37 | if: failure() 38 | with: 39 | name: reports-lecture-python-programming-${{ matrix.os }} 40 | path: lecture-python-programming.myst/lectures/_build/html/reports 41 | - name: Clean (lecture-python-programming) 42 | run: rm -rf lecture-python-programming.myst 43 | - name: Build lecture-python 44 | shell: bash -l {0} 45 | run: | 46 | git clone https://github.com/quantecon/lecture-python.myst 47 | cd lecture-python.myst 48 | jb build lectures -W --keep-going 49 | - name: Upload Execution Reports (lecture-python) 50 | uses: actions/upload-artifact@v4 51 | if: failure() 52 | with: 53 | name: reports-lecture-python-${{ matrix.os }} 54 | path: lecture-python.myst/lectures/_build/html/reports 55 | - name: Clean (lecture-python) 56 | run: rm -rf lecture-python.myst 57 | - name: Build lecture-python-advanced 58 | shell: bash -l {0} 59 | run: | 60 | git clone https://github.com/quantecon/lecture-python-advanced.myst 61 | cd lecture-python-advanced.myst 62 | jb build lectures -W --keep-going 63 | - name: Upload Execution Reports (lecture-python-advanced) 64 | uses: actions/upload-artifact@v4 65 | if: failure() 66 | with: 67 | name: reports-lecture-python-advanced-${{ matrix.os }} 68 | path: lecture-python-advanced.myst/lectures/_build/html/reports 69 | - name: Clean (lecture-python-advanced) 70 | run: rm -rf lecture-python-advanced.myst 71 | - name: Build python-lecture-sandpit.myst 72 | shell: bash -l {0} 73 | run: | 74 | git clone https://github.com/quantecon/python-lecture-sandpit.myst 75 | cd python-lecture-sandpit.myst 76 | jb build lectures 77 | - name: Upload Execution Reports (python-lecture-sandpit.myst) 78 | uses: actions/upload-artifact@v4 79 | if: failure() 80 | with: 81 | name: reports-python-lecture-sandpit.myst-${{ matrix.os }} 82 | path: python-lecture-sandpit.myst/lectures/_build/html/reports 83 | - name: Clean (python-lecture-sandpit.myst) 84 | run: rm -rf python-lecture-sandpit.myst 85 | -------------------------------------------------------------------------------- /.github/workflows/quantecon-env-linux.yml: -------------------------------------------------------------------------------- 1 | name: Test QuantEcon Environment (Linux) 2 | on: 3 | schedule: 4 | # UTC 22:00 is early morning in Australia (Daily) 5 | - cron: '0 22 * * *' 6 | push: 7 | branches: 8 | - main 9 | jobs: 10 | execution-tests-linux: 11 | name: Execution Tests (${{ matrix.python-version }}, ${{ matrix.os }}) 12 | runs-on: ${{ matrix.os }} 13 | strategy: 14 | fail-fast: false 15 | matrix: 16 | os: ["ubuntu-latest"] 17 | python-version: ["3.9"] 18 | steps: 19 | - name: Checkout 20 | uses: actions/checkout@v5 21 | - uses: conda-incubator/setup-miniconda@v3 22 | with: 23 | auto-update-conda: true 24 | auto-activate-base: true 25 | miniconda-version: 'latest' 26 | python-version: ${{ matrix.python-version }} 27 | environment-file: environment.yml 28 | activate-environment: quantecon 29 | - name: Build lecture-python-programming 30 | shell: bash -l {0} 31 | run: | 32 | git clone https://github.com/quantecon/lecture-python-programming.myst 33 | cd lecture-python-programming.myst 34 | jb build lectures -W --keep-going 35 | - name: Upload Execution Reports (lecture-python-programming) 36 | uses: actions/upload-artifact@v4 37 | if: failure() 38 | with: 39 | name: reports-lecture-python-programming-${{ matrix.os }} 40 | path: lecture-python-programming.myst/lectures/_build/html/reports 41 | - name: Clean (lecture-python-programming) 42 | run: rm -rf lecture-python-programming.myst 43 | - name: Build lecture-python 44 | shell: bash -l {0} 45 | run: | 46 | git clone https://github.com/quantecon/lecture-python.myst 47 | cd lecture-python.myst 48 | jb build lectures -W --keep-going 49 | - name: Upload Execution Reports (lecture-python) 50 | uses: actions/upload-artifact@v4 51 | if: failure() 52 | with: 53 | name: reports-lecture-python-${{ matrix.os }} 54 | path: lecture-python.myst/lectures/_build/html/reports 55 | - name: Clean (lecture-python) 56 | run: rm -rf lecture-python.myst 57 | - name: Build lecture-python-advanced 58 | shell: bash -l {0} 59 | run: | 60 | git clone https://github.com/quantecon/lecture-python-advanced.myst 61 | cd lecture-python-advanced.myst 62 | jb build lectures -W --keep-going 63 | - name: Upload Execution Reports (lecture-python-advanced) 64 | uses: actions/upload-artifact@v4 65 | if: failure() 66 | with: 67 | name: reports-lecture-python-advanced-${{ matrix.os }} 68 | path: lecture-python-advanced.myst/lectures/_build/html/reports 69 | - name: Clean (lecture-python-advanced) 70 | run: rm -rf lecture-python-advanced.myst 71 | - name: Build python-lecture-sandpit.myst 72 | shell: bash -l {0} 73 | run: | 74 | git clone https://github.com/quantecon/python-lecture-sandpit.myst 75 | cd python-lecture-sandpit.myst 76 | jb build lectures 77 | - name: Upload Execution Reports (python-lecture-sandpit.myst) 78 | uses: actions/upload-artifact@v4 79 | if: failure() 80 | with: 81 | name: reports-python-lecture-sandpit.myst-${{ matrix.os }} 82 | path: python-lecture-sandpit.myst/lectures/_build/html/reports 83 | - name: Clean (python-lecture-sandpit.myst) 84 | run: rm -rf python-lecture-sandpit.myst 85 | -------------------------------------------------------------------------------- /.github/workflows/quantecon-env-win.yml: -------------------------------------------------------------------------------- 1 | name: Test QuantEcon Environment (Windows) 2 | on: 3 | schedule: 4 | # UTC 22:00 is early morning in Australia on Thursday 5 | - cron: '0 22 * * 4' 6 | push: 7 | branches: 8 | - main 9 | jobs: 10 | execution-tests-win: 11 | name: Execution Tests (${{ matrix.python-version }}, ${{ matrix.os }}) 12 | runs-on: ${{ matrix.os }} 13 | strategy: 14 | fail-fast: false 15 | matrix: 16 | os: ["windows-latest"] 17 | python-version: ["3.9"] 18 | steps: 19 | - name: Checkout 20 | uses: actions/checkout@v5 21 | - uses: conda-incubator/setup-miniconda@v3 22 | with: 23 | auto-update-conda: true 24 | auto-activate-base: true 25 | miniconda-version: 'latest' 26 | python-version: ${{ matrix.python-version }} 27 | environment-file: environment.yml 28 | activate-environment: quantecon 29 | - name: Build lecture-python-programming 30 | shell: powershell 31 | run: | 32 | git clone https://github.com/quantecon/lecture-python-programming.myst 33 | cd lecture-python-programming.myst 34 | jb build lectures -W --keep-going 35 | - name: Upload Execution Reports (lecture-python-programming) 36 | uses: actions/upload-artifact@v4 37 | if: failure() 38 | with: 39 | name: reports-lecture-python-programming-${{ matrix.os }} 40 | path: lecture-python-programming.myst/lectures/_build/html/reports 41 | - name: Clean (lecture-python-programming) 42 | shell: powershell 43 | run: Remove-Item -Recurse -Force lecture-python-programming.myst 44 | - name: Build lecture-python 45 | shell: powershell 46 | run: | 47 | git clone https://github.com/quantecon/lecture-python.myst 48 | cd lecture-python.myst 49 | jb build lectures -W --keep-going 50 | - name: Upload Execution Reports (lecture-python) 51 | uses: actions/upload-artifact@v4 52 | if: failure() 53 | with: 54 | name: reports-lecture-python-${{ matrix.os }} 55 | path: lecture-python.myst/lectures/_build/html/reports 56 | - name: Clean (lecture-python) 57 | shell: powershell 58 | run: Remove-Item -Recurse -Force lecture-python.myst 59 | - name: Build lecture-python-advanced 60 | shell: powershell 61 | run: | 62 | git clone https://github.com/quantecon/lecture-python-advanced.myst 63 | cd lecture-python-advanced.myst 64 | jb build lectures -W --keep-going 65 | - name: Upload Execution Reports (lecture-python-advanced) 66 | uses: actions/upload-artifact@v4 67 | if: failure() 68 | with: 69 | name: reports-lecture-python-advanced-${{ matrix.os }} 70 | path: lecture-python-advanced.myst/lectures/_build/html/reports 71 | - name: Clean (lecture-python-advanced) 72 | shell: powershell 73 | run: Remove-Item -Recurse -Force lecture-python-advanced.myst 74 | - name: Build python-lecture-sandpit.myst 75 | shell: powershell 76 | run: | 77 | git clone https://github.com/quantecon/python-lecture-sandpit.myst 78 | cd python-lecture-sandpit.myst 79 | jb build lectures 80 | - name: Upload Execution Reports (python-lecture-sandpit.myst) 81 | uses: actions/upload-artifact@v4 82 | if: failure() 83 | with: 84 | name: reports-python-lecture-sandpit.myst-${{ matrix.os }} 85 | path: python-lecture-sandpit.myst/lectures/_build/html/reports 86 | - name: Clean (python-lecture-sandpit.myst) 87 | shell: powershell 88 | run: Remove-Item -Recurse -Force python-lecture-sandpit.myst 89 | -------------------------------------------------------------------------------- /.github/copilot-instructions.md: -------------------------------------------------------------------------------- 1 | # QuantEcon .github Repository 2 | 3 | QuantEcon .github repository contains organization-level templates, environment configurations, and CI workflows for building QuantEcon's educational materials using Jupyter Book. This repository primarily supports building and testing lecture repositories across multiple platforms. 4 | 5 | **ALWAYS follow these instructions first and only fallback to additional search and context gathering if the information in these instructions is incomplete or found to be in error.** 6 | 7 | ## Working Effectively 8 | 9 | ### Environment Setup 10 | - Install conda/miniconda if not available: `conda --version` 11 | - **Environment Creation**: `conda env create -f environment.yml` -- takes 15 minutes. NEVER CANCEL. Set timeout to 30+ minutes. 12 | - **Note**: Environment creation may fail due to network timeouts during pip package installation. If this happens, the CI environment typically has packages pre-installed. 13 | 14 | **Alternative: Use existing pre-installed environment (CI environments)**: 15 | - **Activate environment**: `eval "$(conda shell.bash hook)" && conda activate quantecon` 16 | - **Verify installation**: `jupyter-book --version` should show Jupyter Book version information 17 | 18 | ### Building Lecture Repositories 19 | - **ALWAYS** activate the quantecon environment first: `eval "$(conda shell.bash hook)" && conda activate quantecon` 20 | - **Clone lecture repository**: `git clone https://github.com/quantecon/lecture-python-programming.myst` 21 | - **Build lectures**: `cd lecture-python-programming.myst && jb build lectures -W --keep-going` -- takes 4 minutes. NEVER CANCEL. Set timeout to 15+ minutes. 22 | - **Alternative lecture repositories for testing**: 23 | - `https://github.com/quantecon/lecture-python.myst` 24 | - `https://github.com/quantecon/lecture-python-advanced.myst` 25 | - `https://github.com/quantecon/python-lecture-sandpit.myst` 26 | 27 | ### Full CI Workflow Simulation 28 | - **Test Linux workflow locally**: Run the commands from `.github/workflows/quantecon-env-linux.yml` 29 | - **Complete test sequence** (each build takes 4+ minutes): 30 | ```bash 31 | eval "$(conda shell.bash hook)" && conda activate quantecon 32 | 33 | # Test lecture-python-programming 34 | git clone https://github.com/quantecon/lecture-python-programming.myst 35 | cd lecture-python-programming.myst 36 | jb build lectures -W --keep-going 37 | cd .. && rm -rf lecture-python-programming.myst 38 | 39 | # Test lecture-python 40 | git clone https://github.com/quantecon/lecture-python.myst 41 | cd lecture-python.myst 42 | jb build lectures -W --keep-going 43 | cd .. && rm -rf lecture-python.myst 44 | 45 | # Test lecture-python-advanced 46 | git clone https://github.com/quantecon/lecture-python-advanced.myst 47 | cd lecture-python-advanced.myst 48 | jb build lectures -W --keep-going 49 | cd .. && rm -rf lecture-python-advanced.myst 50 | 51 | # Test python-lecture-sandpit 52 | git clone https://github.com/quantecon/python-lecture-sandpit.myst 53 | cd python-lecture-sandpit.myst 54 | jb build lectures 55 | cd .. && rm -rf python-lecture-sandpit.myst 56 | ``` 57 | - **Total time for full workflow**: 25+ minutes (15 min setup + 4 min × 4 builds). NEVER CANCEL. Set timeout to 45+ minutes. 58 | 59 | ## Validation 60 | 61 | - **Always test environment setup** before making changes to environment.yml: 62 | 1. Create test environment with your changes 63 | 2. Activate environment and verify `jupyter-book --version` works 64 | 3. Clone and build at least one lecture repository to verify full functionality 65 | - **Build validation scenario**: After any changes, always test building `lecture-python-programming.myst` as it represents the standard workflow 66 | - **Expected warnings**: Builds typically complete with warnings (exit code 1) - this is normal. Check for actual HTML output in `_build/html/` directory 67 | - **Manual verification steps**: 68 | 1. Verify HTML files are generated: `ls -la lectures/_build/html/*.html` 69 | 2. Check for key files: `intro.html`, main lecture files, and `_static/` directory 70 | 3. Verify build reports: `ls -la lectures/_build/html/reports/` 71 | 72 | ## Critical Timing Information 73 | 74 | - **Environment Creation**: 15 minutes -- NEVER CANCEL. Allow 30+ minute timeout. 75 | - **Single Lecture Build**: 4 minutes -- NEVER CANCEL. Allow 15+ minute timeout. 76 | - **Full CI Workflow**: 25+ minutes total -- NEVER CANCEL. Allow 45+ minute timeout. 77 | - **Large Package Downloads**: The anaconda package is very large (~280MB). Network speed affects timing. 78 | 79 | ## Known Issues and Workarounds 80 | 81 | - **Network timeouts during environment creation**: The `conda env create` command may fail with pip timeout errors when downloading packages from PyPI. This is common in CI environments with network restrictions. Use the pre-installed environment when available. 82 | - **Build warnings**: Jupyter Book builds typically show warnings and return exit code 1, but still produce valid output. Check `_build/html/` for actual results. 83 | - **Network dependencies**: Some builds may fail to fetch external inventories (e.g., jax.quantecon.org) due to network restrictions - this is expected and doesn't prevent successful builds. 84 | - **Conda base environment warnings**: conda often shows warnings about newer versions available - these can be ignored. 85 | 86 | ## Repository Structure 87 | 88 | ### Key Files 89 | - `environment.yml`: Main conda environment specification 90 | - `.github/workflows/quantecon-env-*.yml`: CI workflows for Linux, macOS, Windows testing 91 | - `.github/dependabot.yml`: Dependabot configuration for GitHub Actions updates 92 | - `FUNDING.yml`: Sponsorship configuration 93 | - `lectures/README.md`: Template for lecture repository README files 94 | 95 | ### GitHub Actions Workflows 96 | - **quantecon-env-linux.yml**: Daily testing on Ubuntu (complete workflow) 97 | - **quantecon-env-osx.yml**: Weekly testing on macOS (Monday) 98 | - **quantecon-env-win.yml**: Weekly testing on Windows (Thursday) 99 | - All workflows test building the same 4 lecture repositories 100 | 101 | ## Common Commands Reference 102 | 103 | ```bash 104 | # Environment setup 105 | conda env create -f environment.yml 106 | 107 | # Environment setup (Alternative: Use existing environment in CI) 108 | eval "$(conda shell.bash hook)" && conda activate quantecon 109 | 110 | # Quick validation 111 | jupyter-book --version 112 | which jupyter-book 113 | 114 | # Single repository test 115 | git clone https://github.com/quantecon/lecture-python-programming.myst 116 | cd lecture-python-programming.myst 117 | jb build lectures -W --keep-going 118 | 119 | # Check build results 120 | ls -la lectures/_build/html/ 121 | ls -la lectures/_build/html/reports/ 122 | 123 | # Clean up 124 | cd .. && rm -rf lecture-python-programming.myst 125 | ``` 126 | 127 | ### Expected Command Output 128 | 129 | #### conda env create -f environment.yml 130 | ``` 131 | # Takes ~15 minutes, downloads ~280MB of packages 132 | # Shows package resolution, downloading, and installation progress 133 | # Ends with: "done" and activation instructions 134 | ``` 135 | 136 | #### jupyter-book --version 137 | ``` 138 | # Shows current Jupyter Book version and dependencies 139 | # Example output format: 140 | # Jupyter Book : 1.0.x.postX 141 | # External ToC : X.X.X 142 | # MyST-Parser : X.X.X 143 | # MyST-NB : X.X.X 144 | # Sphinx Book Theme : X.X.X 145 | # Jupyter-Cache : X.X.X 146 | # NbClient : X.X.X 147 | ``` 148 | 149 | #### jb build lectures -W --keep-going 150 | ``` 151 | # Takes ~4 minutes 152 | # Shows Jupyter-Book and Sphinx build progress 153 | # Typically ends with "build finished with problems, X warnings" 154 | # Exit code 1 is normal - check _build/html/ for actual output 155 | ``` --------------------------------------------------------------------------------