Config & Options

Important Options and Config for Python Devs

Hamel Husain

Parlance Labs

Hierachy

Cells > Front Matter > Project Level

For example, see the reference docs:

• Cells: see code cells.
• Front matter: see HTML format.
• Project Level: see project options some of these can also live in front-matter.

There is overlap! See echo:false in cell options, vs execute: echo:false in front matter.

Directory Level Config

• Use _metadata.yml, which gets merged.
• The more specific config controls (cell > front matter > project).
• Breaking _quarto.yml into multiple files using metadata-files: [config.yml].
  • This can also be used in front matter: see this example, which you can also find in the docs.

Cell Options

Use the #| syntax to specify cell options:

#| echo: false
print('hello')

My favorite cell options:

• eval: evaluate code cells
• echo: show/hide code cells
• output: show/hide cell output
• include: show/hide cell input & output (catch-all)

See more.

Look at the source

I looked at this page when making this slide.

Execution Options

Engine binding:

jupyter:
  kernelspec:
    display_name: Python 3
    language: python
    name: python3
execute:
  echo: false

Output Options:

As an example, let’s consider echo:false, this can also be in front matter:

quarto.yml

execute: 
  echo: false

Freezing

execute:
  freeze: true  # never re-render during project render

execute:
  freeze: auto # re-render ONLY if source changes

Jupyter Cache

To use Jupyter Cache you’ll want to first install the jupyter-cache package:

Platform	Command
Mac/Linux	Terminal python3 -m pip install jupyter-cache
Windows	Terminal py -m pip install jupyter-cache

Jupyter Cache Options

To enable the cache for a document, add the cache option. For example:

---
title: "My Document"
format: html
execute: 
  cache: true
---

You can also specify caching at the project level in the _quarto.yml file:

execute:
  cache: true

And also at a cell level:

#| cache: true
def foo(): ...

See execution options.

New features in Quarto 1.4

• Inline Execution
• Rendering script files

See the release notes here and on GitHub.

What I do as a Python developer

1. Use notebooks anytime there is code.
2. Use .qmd with VSCode if not much code.
3. Use cell options heavily.
4. Sometimes, I want to disable an entire notebook from running, so I use execute: false in front matter.

execute:
  eval: false

5. Using shell commands with iPython magic with !.
6. Most importantly: look at examples!

• I like #|eval: false in notebooks, b/c unlike .qmd, output is saved.

• I also helped develop a way to develop entire Python libraries with notebooks that leverages Quarto called nbdev, which I’ll talk about in the afternoon.

Make your code more visibile

Use GitHub links:

website:
  repo-url: https://github.com/quarto-dev/quarto-demo
  repo-actions: [edit, issue]

You can also set a specific branch, ex: repo-branch: master.

Other important tips

• If using notebooks, front matter goes in a raw cell! (Show you)
• You can embed notebook cells in .qmd files which allows you to get the best of both worlds.
• Use the features of the Quarto extension for VSCode.

Exercise

1. Create a new project with quarto new and add a notebook.
2. Create a separate metadata.yml file with configuration.
3. Create a blog listings section.
4. Create a notes section with a hierarchy represented with folders. Example
5. Take an example from Wasim’s page and adapt it to your own site.
6. Turn on comments for your blog posts.