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 previewqpyd: site commands
qpyd prerender
Runs the pre-render build steps, in order:
quartodoc build— generate the API reference pages.- Customize aliases — add short cross-reference aliases (e.g.
pkg.Thingforpkg.submodule.Thing) toobjects.json. quartodoc interlinks— build interlink inventories (only ifinterlinks.sourceslists other sites’ docs).- Build a Sphinx-compatible
objects.invso other projects can resolve your references via intersphinx. - 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 stepsqpyd preview
Like qpyd render, but launches quarto preview (a live-reloading server) after the pre-render steps:
qpyd preview
qpyd preview --no-prerenderqpyd gh-publish
Renders with --cache-refresh and publishes to the gh-pages branch via quarto publish.
qpyd gh-publishThis 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_packageqpyd 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 deletedqpynb: 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)runrenders each notebook withquarto 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.checkis 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 witheval: falseare skipped, and errors in cells witherror: trueare allowed (both as#|cell options or in the page’sexecuteoptions).
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-runqpynb 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.qmdqpynb 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’sversion.py,_version.py,__version__.py,__about__.pyand__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: MITIf 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