Skip to content

[Experimental] Use mystmd to build lectures #345

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 15 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 36 additions & 56 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -5,69 +5,49 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Anaconda
uses: conda-incubator/setup-miniconda@v3

- name: Setup GitHub Pages
uses: actions/configure-pages@v3

- name: Cache Notebook Execution
uses: actions/cache@v3
id: cache-execution
with:
auto-update-conda: true
auto-activate-base: true
miniconda-version: 'latest'
python-version: "3.12"
environment-file: environment.yml
activate-environment: quantecon
- name: Install latex dependencies
run: |
sudo apt-get -qq update
sudo apt-get install -y \
texlive-latex-recommended \
texlive-latex-extra \
texlive-fonts-recommended \
texlive-fonts-extra \
texlive-xetex \
latexmk \
xindy \
dvipng \
cm-super
- name: Display Conda Environment Versions
shell: bash -l {0}
run: conda list
- name: Display Pip Versions
shell: bash -l {0}
run: pip list
- name: Download "build" folder (cache)
uses: dawidd6/action-download-artifact@v9
path: ./lectures/_build/execute
key: ${{ runner.os }}-execute-cache-${{ hashFiles('lectures/**/*.md') }}

- uses: actions/setup-node@v4
with:
workflow: cache.yml
branch: main
name: build-cache
path: _build
# Build Assets (Download Notebooks and PDF via LaTeX)
- name: Build Download Notebooks (sphinx-tojupyter)
shell: bash -l {0}
run: |
jb build lectures --path-output ./ --builder=custom --custom-builder=jupyter -n -W --keep-going
mkdir -p _build/html/_notebooks
cp -u _build/jupyter/*.ipynb _build/html/_notebooks
- name: Build PDF from LaTeX
shell: bash -l {0}
run: |
jb build lectures --builder pdflatex --path-output ./ -n -W --keep-going
mkdir _build/html/_pdf
cp -u _build/latex/*.pdf _build/html/_pdf
# Final Build of HTML
node-version: 18.x

- name: Install Python
if: steps.cache-execution.outputs.cache-hit != 'true'
uses: actions/setup-python@v5
with:
python-version: '3.12'
cache: 'pip'
cache-dependency-path: 'myst_requirements.txt'

- name: Install execution requirements
if: steps.cache-execution.outputs.cache-hit != 'true'
run: python -m pip install -r myst_requirements.txt

- name: Install MyST Markdown CLI
run: npm install -g mystmd

- name: Build HTML
shell: bash -l {0}
run: |
jb build lectures --path-output ./ -n -W --keep-going
- name: Upload Execution Reports
uses: actions/upload-artifact@v4
if: failure()
working-directory: ./lectures
run: myst build --html --execute

- name: Upload build output
uses: actions/upload-pages-artifact@v3
with:
name: execution-reports
path: _build/html/reports
path: './lectures/_build/html'

- name: Preview Deploy to Netlify
uses: nwtgck/actions-netlify@v3
with:
publish-dir: '_build/html/'
publish-dir: './lectures/_build/html'
production-branch: main
github-token: ${{ secrets.GITHUB_TOKEN }}
deploy-message: "Preview Deploy from GitHub Actions"
Binary file added lectures/_static/ccbysa.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
28 changes: 3 additions & 25 deletions lectures/about_py.md
Original file line number Diff line number Diff line change
@@ -9,17 +9,6 @@ kernelspec:
name: python3
---

(about_py)=
```{raw} jupyter
<div id="qe-notebook-header" align="right" style="text-align:right;">
<a href="https://quantecon.org/" title="quantecon.org">
<img style="width:250px;display:inline;" width="250px" src="https://assets.quantecon.org/img/qe-menubar-logo.svg" alt="QuantEcon">
</a>
</div>
```

```{index} single: python
```

# About These Lectures

@@ -95,7 +84,7 @@ This is important because it

### Common Uses

{index}`Python <single: Python; common uses>` is a general-purpose language used in almost all application domains, including
Python is a general-purpose language used in almost all application domains, including

* AI
* scientific computing
@@ -164,8 +153,6 @@ Other features of Python:

### Syntax and Design

```{index} single: Python; syntax and design
```

One reason for Python's popularity is its simple and elegant design --- we'll see many examples later on.

@@ -283,8 +270,6 @@ These lectures will explain how.

## Scientific Programming with Python

```{index} single: scientific programming
```

We have already discussed the importance of Python for AI, machine learning and data science

@@ -308,9 +293,6 @@ This section briefly showcases some examples of Python for general scientific pr

### NumPy

```{index} single: scientific programming; numeric
```

One of the most important parts of scientific computing is working with data.

Data is often stored in matrices, vectors and arrays.
@@ -411,8 +393,6 @@ Later we'll discuss SciPy in more detail.

### Graphics

```{index} single: Matplotlib
```

A major strength of Python is data visualization.

@@ -425,13 +405,13 @@ The most popular and comprehensive Python library for creating figures and graph
Example 2D plot with embedded LaTeX annotations

```{figure} /_static/lecture_specific/about_py/qs.png
:scale: 75
:width: 75%
```

Example contour plot

```{figure} /_static/lecture_specific/about_py/bn_density1.png
:scale: 70
:width: 70%
```

Example 3D plot
@@ -467,8 +447,6 @@ For example, we are interesting in studying

Python has many libraries for studying networks and graphs.

```{index} single: NetworkX
```

One well-known example is [NetworkX](http://networkx.github.io/).

77 changes: 22 additions & 55 deletions lectures/debugging.md
Original file line number Diff line number Diff line change
@@ -9,20 +9,8 @@ kernelspec:
name: python3
---

(debugging)=
```{raw} jupyter
<div id="qe-notebook-header" align="right" style="text-align:right;">
<a href="https://quantecon.org/" title="quantecon.org">
<img style="width:250px;display:inline;" width="250px" src="https://assets.quantecon.org/img/qe-menubar-logo.svg" alt="QuantEcon">
</a>
</div>
```

# Debugging and Handling Errors

```{index} single: Debugging
```

```{epigraph}
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are, by definition,
@@ -45,9 +33,6 @@ In this lecture, we will discuss how to debug our programs and improve error han

## Debugging

```{index} single: Debugging
```

Debugging tools for Python vary across platforms, IDEs and editors.

For example, a [visual debugger](https://jupyterlab.readthedocs.io/en/stable/user/debugger.html) is available in JupyterLab.
@@ -67,9 +52,8 @@ import matplotlib.pyplot as plt
Let's consider a simple (and rather contrived) example

```{code-cell} ipython
---
tags: [raises-exception]
---
:tags: raises-exception
def plot_log():
fig, ax = plt.subplots(2, 1)
x = np.linspace(1, 2, 10)
@@ -94,9 +78,8 @@ But let's pretend that we don't understand this for the moment.
We might suspect there's something wrong with `ax` but when we try to investigate this object, we get the following exception:

```{code-cell} python3
---
tags: [raises-exception]
---
:tags: raises-exception
ax
```

@@ -108,9 +91,8 @@ Let's try doing it a different way.
We run the first cell block again, generating the same error

```{code-cell} python3
---
tags: [raises-exception]
---
:tags: raises-exception
def plot_log():
fig, ax = plt.subplots(2, 1)
x = np.linspace(1, 2, 10)
@@ -187,9 +169,8 @@ The preceding approach is handy but sometimes insufficient.
Consider the following modified version of our function above

```{code-cell} python3
---
tags: [raises-exception]
---
:tags: raises-exception
def plot_log():
fig, ax = plt.subplots()
x = np.logspace(1, 2, 10)
@@ -259,8 +240,6 @@ The full list of magics is [here](http://ipython.readthedocs.org/en/stable/inter

## Handling Errors

```{index} single: Python; Handling Errors
```

Sometimes it's possible to anticipate bugs and errors as we're writing code.

@@ -292,19 +271,16 @@ In this section, we'll discuss different types of errors in Python and technique

### Errors in Python

We have seen `AttributeError` and `NameError` in {any}`our previous examples <debug_magic>`.
We have seen `AttributeError` and `NameError` in [our previous examples](#debug_magic).

In Python, there are two types of errors -- syntax errors and exceptions.

```{index} single: Python; Exceptions
```

Here's an example of a common error type

```{code-cell} python3
---
tags: [raises-exception]
---
:tags: raises-exception
def f:
```

@@ -313,36 +289,32 @@ Since illegal syntax cannot be executed, a syntax error terminates execution of
Here's a different kind of error, unrelated to syntax

```{code-cell} python3
---
tags: [raises-exception]
---
:tags: raises-exception
1 / 0
```

Here's another

```{code-cell} python3
---
tags: [raises-exception]
---
:tags: raises-exception
x1 = y1
```

And another

```{code-cell} python3
---
tags: [raises-exception]
---
:tags: raises-exception
'foo' + 6
```

And another

```{code-cell} python3
---
tags: [raises-exception]
---
:tags: raises-exception
X = []
x = X[0]
```
@@ -355,8 +327,6 @@ In Python, these errors are called *exceptions*.

### Assertions

```{index} single: Python; Assertions
```

Sometimes errors can be avoided by checking whether your program runs as expected.

@@ -376,9 +346,8 @@ If we run this with an array of length one, the program will terminate and
print our error message

```{code-cell} python3
---
tags: [raises-exception]
---
:tags: raises-exception
var([1])
```

@@ -389,8 +358,6 @@ The advantage is that we can

### Handling Errors During Runtime

```{index} single: Python; Runtime Errors
```

The approach used above is a bit limited, because it always leads to
termination.
@@ -508,7 +475,7 @@ prices

Using `try` -- `except`, write a program to read in the contents of the file and sum the numbers, ignoring lines without numbers.

You can use the `open()` function we learnt {any}`before<iterators>` to open `numbers.txt`.
You can use the `open()` function we learnt [before](#iterators) to open `numbers.txt`.
```{exercise-end}
```

2 changes: 2 additions & 0 deletions lectures/foo.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@

print("foobar")
Loading