Historical Record: Removal of :load: Directives in Cake Eating Series (PR #679)

[mmcky]

Context

As part of PR #679 (Refactor optimal growth lectures into unified cake eating series), we removed all :load: directives from the affected lectures and inlined the code directly.

Motivation

The :load: directive was removed to make lectures:

1. Self-contained - All code visible in the lecture file itself
2. Compatible with jupytext - Enables easy conversion to executable Python with jupytext --to py
3. Easier to maintain - No need to track external code files

Lectures That Had :load: Directives Removed

Lecture File	External Code File(s) Loaded	Purpose
cake_eating_numerical.md	_static/lecture_specific/cake_eating_numerical/analytical.py	Analytical solutions (c_star, v_star functions)
cake_eating_stochastic.md (formerly optgrowth.md)	_static/lecture_specific/optgrowth/cd_analytical.py	Analytical solutions for Cobb-Douglas case
cake_eating_stochastic.md	_static/lecture_specific/optgrowth/solve_model.py	solve_model() function for value function iteration
cake_eating_time_iter.md (formerly coleman_policy_iter.md)	_static/lecture_specific/optgrowth/cd_analytical.py	Analytical solutions
cake_eating_egm.md (formerly egm_policy_iter.md)	_static/lecture_specific/optgrowth/cd_analytical.py	Analytical solutions
cake_eating_egm.md	_static/lecture_specific/coleman_policy_iter/solve_time_iter.py	solve_model_time_iter() function
ifp.md	_static/lecture_specific/coleman_policy_iter/solve_time_iter.py	solve_model_time_iter() function
ifp.md	_static/lecture_specific/cake_eating_numerical/analytical.py	Analytical solutions for cake eating
optgrowth_fast.md (deleted)	_static/lecture_specific/optgrowth_fast/ogm.py	OptimalGrowthModel class
optgrowth_fast.md (deleted)	_static/lecture_specific/optgrowth_fast/ogm_crra.py	OptimalGrowthModel_CRRA class
optgrowth_fast.md (deleted)	_static/lecture_specific/optgrowth/cd_analytical.py	Analytical solutions
optgrowth_fast.md (deleted)	_static/lecture_specific/optgrowth/solve_model.py	solve_model() function

External Code Files That Were Loaded

• _static/lecture_specific/cake_eating_numerical/analytical.py
• _static/lecture_specific/optgrowth/cd_analytical.py
• _static/lecture_specific/optgrowth/solve_model.py
• _static/lecture_specific/coleman_policy_iter/solve_time_iter.py
• _static/lecture_specific/optgrowth_fast/ogm.py
• _static/lecture_specific/optgrowth_fast/ogm_crra.py

Files Deleted

The following external Python files were deleted after their content was inlined:

• _static/lecture_specific/cake_eating_numerical/analytical.py
• _static/lecture_specific/optgrowth/cd_analytical.py
• _static/lecture_specific/optgrowth/solve_model.py

Impact

• 8 lecture files had :load: directives removed
• All affected lectures now contain inline code
• No functionality changed - only code organization
• Lectures are now fully executable via jupytext --to py lectures/filename.md

Related

• PR Refactor optimal growth lectures into unified cake eating series #679: Refactor optimal growth lectures into unified cake eating series
• Comment from @jstac: "I really need to be able to easily generate executable code via jupytext --to py..."

Future Considerations

Going forward, we should prefer inline code over external :load: files for:

• Better jupytext compatibility
• Improved readability (all code visible in context)
• Easier maintenance

The :load: directive may still be useful for:

• Very large helper modules (>100 lines)
• Code shared across many lectures (though this should be in a proper Python package)
• Utility functions that would clutter the pedagogical flow

---

This issue serves as historical documentation and does not require action.

[jstac]

Thanks @mmcky , I agree with all of the above.

[mmcky]

Thanks @jstac -- I actually think for shared code a lecture-python package would be the way to go and we build a directive for showing the actual code from the package.

I've had some ideas around this concept.

```{code-source} ipython3
:package: qe_lectures
:function: function
:executable: true
:show: 20                     # collapsible with 20 lines 
```

would bring in the code from the package and include it as executable {code-cell} directive.

So you can use the function

a = function(x,y)

the only tricky part is if the function depends on another part of the package (but should be fixable through imports), or style rules to ensure importable lecture functions remain independent.

[mmcky]

@jstac actually this concept wouldn't help with jupytext as it would require jupyter-book ast parsing. 🤔

[jstac]

I actually think that we have so little in the way of shared code between lectures, relative to the total volume of code, that we can just drop it as a convention. anything that we really repeat a lot we can put in quantecon (py lib). for code we repeat a bit, we can manage it with AI ("search for all instances of the function xyz and modify as follows...").

It cuts out another layer of complexity.