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 13 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
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
Expand Up @@ -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"
Expand Down
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
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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

Expand All @@ -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.
Expand Down Expand Up @@ -411,8 +393,6 @@ Later we'll discuss SciPy in more detail.

### Graphics

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

A major strength of Python is data visualization.

Expand All @@ -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
Expand Down Expand Up @@ -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/).

Expand Down
77 changes: 22 additions & 55 deletions lectures/debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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.
Expand All @@ -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)
Expand All @@ -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
```

Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:
```

Expand All @@ -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]
```
Expand All @@ -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.

Expand All @@ -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])
```

Expand All @@ -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.
Expand Down Expand Up @@ -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}
```

Expand Down
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