Skip to main content

The qpyd CLI

tl;dr: qpyd is a higher-level command-line workflow built on top of quartodoc. Where quartodoc build generates your API reference pages, qpyd wraps the whole docs lifecycle — pre-render builds, rendering, previewing, publishing, scaffolding — and adds parallel notebook management.

It installs two console scripts:

Command Purpose
qpyd Build, render, preview, publish, and scaffold a docs site.
qpynb Run, check, convert, and clean notebooks (.qmd / .ipynb). Also available as qpyd nb ….

Both accept --help and --version.

qpyd builds on sciris, jupytext, and nbformat, and shells out to the external quarto binary, so make sure Quarto is installed and on your PATH.

Quick start

Scaffold a docs folder, then render it:

# Create docs/ with a starter _quarto.yml, index.qmd, and _variables.py
qpyd init docs --package your_package

cd docs

# Run pre-render steps, then `quarto render`
qpyd render

# Or preview with live reload
qpyd preview

qpyd: site commands

qpyd prerender

Runs the pre-render build steps, in order:

  1. quartodoc build — generate the API reference pages.
  2. Customize aliases — add short cross-reference aliases (e.g. pkg.Thing for pkg.submodule.Thing) to objects.json.
  3. quartodoc interlinks — build interlink inventories (only if interlinks.sources lists other sites’ docs).
  4. Build a Sphinx-compatible objects.inv so other projects can resolve your references via intersphinx.
  5. Run any project-specific commands listed in qpyd.prerender.commands.

Before these, it writes the values from _variables.py to _variables.yml.

qpyd prerender          # skips the build if nothing it depends on changed
qpyd prerender --force  # rebuild anyway (or set QPYD_FORCE_PRERENDER=1)

The build only depends on the documented package’s source, quartodoc itself, _quarto.yml, and any qpyd.prerender.inputs, so it is skipped when none of these changed since the last build and its outputs (objects.json, objects.inv, the API pages, and any qpyd.prerender.outputs) are all there. The hash of the inputs is kept in .quarto/qpyd-prerender.json.

The documented package name is read from the quartodoc.package key in your _quarto.yml. This is the command you typically wire into your project’s pre-render hook (see below). As a hook, it does nothing when Quarto is rendering only some pages (e.g. quarto render page.qmd), so those renders stay fast.

qpyd render

Runs qpyd prerender, then quarto render, reporting the total build time. Any extra arguments are passed straight through to Quarto:

qpyd render                 # full build
qpyd render --to html       # extra args forwarded to `quarto render`
qpyd render --no-prerender  # skip the pre-render steps

qpyd preview

Like qpyd render, but launches quarto preview (a live-reloading server) after the pre-render steps:

qpyd preview
qpyd preview --no-prerender

qpyd gh-publish

Renders with --cache-refresh and publishes to the gh-pages branch via quarto publish.

qpyd gh-publish
Warning

This pushes to a remote branch and updates your live site. It is never run as part of any other command.

qpyd init

Scaffolds a docs folder with a starter _quarto.yml, index.qmd, and _variables.py. Existing files are never overwritten, so it is safe to run in an established project.

qpyd init docs --package your_package

qpyd clean

Deletes auto-generated scratch files after a build. This is opt-in: it only removes files (and folders) matching the qpyd.clean glob patterns in your _quarto.yml, and it never deletes source files (.qmd, .ipynb, .py, .md), or folders that contain any. Like qpyd prerender, it does nothing as a post-render hook for renders of only some pages.

qpyd clean            # delete configured scratch files
qpyd clean --dry-run  # show what would be deleted

qpynb: notebook commands

A “notebook” is an .ipynb file, or a .qmd file containing a {python} code cell. Commands that take paths accept individual notebooks or folders; omit them to operate on the whole project.

qpynb run and qpynb check

Both execute notebooks in parallel. The difference is what they do with the cache:

qpynb run            # execute via `quarto render`, updating the _freeze/ cache
qpynb check          # execute to verify they run; touch no caches, leave no files
qpynb run tutorials  # only the notebooks under tutorials/
qpynb check --serial # one at a time (useful for debugging)
  • run renders each notebook with quarto render, which executes it and refreshes Quarto’s freeze cache (_freeze/). Use it to pre-bake the cache in parallel so a subsequent full-site render is fast.
  • check is a pure validation pass — it executes each notebook to confirm it runs without error, but writes no cache and leaves nothing behind. This is ideal for CI. It runs what the rendered page would: cells with eval: false are skipped, and errors in cells with error: true are allowed (both as #| cell options or in the page’s execute options).

During run, each per-notebook render sets QPYD_SKIP_HOOKS=1, so a project pre-render: qpyd prerender hook becomes a no-op rather than rebuilding the whole API reference (and racing on objects.json) once per notebook.

qpynb refresh

Deletes the cached copies of notebooks — Quarto’s freeze cache (_freeze/) and every nested jupyter cache (.jupyter_cache/) — so they re-execute on the next render.

qpynb refresh
qpynb refresh --dry-run

qpynb to-py / to-qmd / to-ipynb

Convert a notebook between formats. .qmd ⇄ .ipynb conversions go through quarto convert; anything involving .py uses jupytext. The destination is not overwritten unless you pass --force.

qpynb to-py tutorials/intro.qmd      # -> tutorials/intro.py
qpynb to-ipynb tutorials/intro.qmd   # -> tutorials/intro.ipynb
qpynb to-qmd notebook.ipynb --force  # overwrite an existing notebook.qmd

qpynb clear

Strips saved outputs and execution counts from .ipynb notebooks and normalizes them. Files that are already clean are left untouched.

qpynb clear
qpynb clear --dry-run

_variables.py

You can place an optional _variables.py file alongside _quarto.yml. qpyd prerender writes its values to _variables.yml (keeping any other keys there), so the var shortcode can use them however the site is rendered:

# _variables.py
import quartodoc as qd

version = qd.get_version()
versiondate = qd.get_attr("__versiondate__")

qd.get_version() and qd.get_attr() read the documented package (the quartodoc.package key) from its source, without importing it, which keeps renders fast even for packages that are slow to import:

  • get_version(package=None) returns the package’s __version__ if its source defines one as a literal, and otherwise the installed version (e.g. for versions from git tags).
  • get_attr(name, package=None, default=...) returns any module-level constant that is assigned a literal value (a string, number, list, dict, …), looking in the package’s version.py, _version.py, __version__.py, __about__.py and __init__.py. A dotted name says which module to read, e.g. qd.get_attr("pkg.meta.__citation__").

Reference them in documents with:

Docs for version {{< var version >}} ({{< var versiondate >}}).

If _variables.py defines __all__, exactly those names are exported. Otherwise every name is, except private ones (starting with _), modules, and callables (functions and classes). A value that can’t be written to YAML, such as a NumPy number, is skipped with a warning, so convert it to a string or number first.

For the common case, you don’t need _variables.py at all: declare the variables in the qpyd.variables section of _quarto.yml instead. A value of the form {attr: NAME} is read from the package’s source, just like qd.get_attr() (and {attr: __version__} like qd.get_version()); any other value is used as is:

qpyd:
  variables:
    version: {attr: __version__}
    versiondate: {attr: __versiondate__}
    sciris_version: {attr: sciris.__version__}  # a dotted name reads another package
    license: MIT

If a name is in both, _variables.py wins.

Since _variables.py runs on every render, keep it quick: prefer qd.get_version() and qd.get_attr() to importing a large package.

Configuring _quarto.yml

The keys qpyd reads or writes:

project:
  pre-render: qpyd prerender   # build API docs etc. before each render
  # post-render: qpyd clean    # optional; opt-in scratch cleanup

quartodoc:
  package: your_package        # used by prerender for aliases / objects.inv

qpyd:
  prerender:                   # optional project-specific pre-render steps
    commands:                  # run after the standard steps, in the docs folder
      - python make_index.py
    inputs: [make_index.py]    # extra files the build depends on (globs allowed)
    outputs: [index.json]      # extra files it creates
  clean:                       # optional glob patterns for `qpyd clean`
    - '**/my-*.png'            # source files are never deleted, even if matched
  variables:                   # optional docs variables (see above)
    version: {attr: __version__}

execute:
  freeze: auto                 # let `qpynb run` pre-bake the freeze cache