quarto

Install and interact with Quarto from nbdev

Helpful background on how Quarto fits in here: https://nbdev.fast.ai/explanations/docs.html

Install

install_quarto

def install_quarto():

Install latest Quarto on macOS or Linux, prints instructions for Windows

source

install

def install():

Install Quarto and the current library

Sidebar

source

IndentDumper

def IndentDumper(
    stream, default_style:NoneType=None, default_flow_style:bool=False, canonical:NoneType=None,
    indent:NoneType=None, width:NoneType=None, allow_unicode:NoneType=None, line_break:NoneType=None,
    encoding:NoneType=None, explicit_start:NoneType=None, explicit_end:NoneType=None, version:NoneType=None,
    tags:NoneType=None, sort_keys:bool=True
):

source

nbdev_sidebar

def nbdev_sidebar(
    path:str=None, # Path to notebooks
    printit:bool=False, # Print YAML for debugging
    force:bool=False, # Create sidebar even if custom_sidebar=false in pyproject.toml
    skip_folder_re:str='(?:^[_.]|^www\\$)', # Skip folders matching regex
):

Create sidebar.yml

# nbdev_sidebar(printit=True, force=True)

Render docs

source

refresh_quarto_yml

def refresh_quarto_yml():

Generate _quarto.yml from pyproject.toml.

source

nbdev_proc_nbs

def nbdev_proc_nbs(
    *, path:str='', # Path to notebooks
    n_workers:int=4, # Number of workers
    force:bool=False, # Ignore cache and build all
    file_glob:str='', # Only process notebooks matching glob (other files are always included)
    file_re:str='', # Only process notebooks matching regex (other files are always included)
    symlinks:bool=False, # Follow symlinks?
    folder_re:str=None, # Only enter folders matching regex
    skip_file_glob:str=None, # Skip files matching glob
    skip_file_re:str='^[_.]', # Skip files matching regex
    skip_folder_re:str='^[_.]', # Skip folders matching regex
):

Process notebooks in path for docs rendering

source

nbdev_readme

def nbdev_readme(
    path:str=None, # Path to notebooks (or project root)
    chk_time:bool=False, # Only build if out of date
):

Create README.md from readme_nb (index.ipynb by default). Skips if the file doesn’t exist.

nbdev-readme calls “quarto render,” which is explained in the Quarto guide here.

Pandoc’s gfm writer hard-wraps prose at 72 columns by default; -M wrap:preserve keeps each paragraph’s line breaks exactly as authored in the notebook instead.

Only the readme notebook itself is processed (plus non-notebook assets like images), so building the README never executes code from the project’s other notebooks; and if the readme notebook doesn’t exist, the command just returns.

source

nbdev_contributing

def nbdev_contributing(
    path:str=None, # Path to notebooks
    chk_time:bool=False, # Only build if out-of-date
):

Create CONTRIBUTING.md from contributing_nb (defaults to ‘contributing.ipynb’ if present). Skips if the file doesn’t exist.

Quarto’s quarto-nav.js rewrites /index.html links to / for clean URLs, but the regex is unanchored, so on a site’s index page it also mangles the “Other Formats” CommonMark link: index.html.md becomes .md (quarto-dev/quarto-cli#14667). _fix_quarto_nav anchors the regex in the rendered site’s copy of the script. Once quarto fixes it upstream, the pattern no longer matches and this becomes a no-op.

with tempfile.TemporaryDirectory() as d:
    nav = Path(d)/'site_libs/quarto-nav/quarto-nav.js'
    nav.parent.mkdir(parents=True)
    nav.write_text(r'x.replace(/\/index\.html/, "/");')
    _fix_quarto_nav(d)
    test_eq(nav.read_text(), r'x.replace(/\/index\.html(?=[?#]|$)/, "/");')
    _fix_quarto_nav(d)   # idempotent, and a no-op once quarto fixes the regex upstream
    test_eq(nav.read_text(), r'x.replace(/\/index\.html(?=[?#]|$)/, "/");')

source

nbdev_docs

def nbdev_docs(
    path:str=None, # Path to notebooks
    n_workers:int=4, # Number of workers
):

Create Quarto docs and README.md

source

prepare

def prepare():

Export, test, and clean notebooks, and render README if needed

Preview

source

fs_watchdog

def fs_watchdog(
    func, path, recursive:bool=True
):

File system watchdog dispatching to func

source

nbdev_preview

def nbdev_preview(
    path:str=None, # Path to notebooks
    port:int=None, # The port on which to run preview
    host:str=None, # The host on which to run preview
    no_browser:bool=False, # Do not open a browser
    n_workers:int=4, # Number of workers
):

Preview docs locally