실행 관리

개요

입력 파일 목록을 렌더링하는 작업은 필요한 계산에 따라 시간이 오래 걸릴 수 있습니다. 계산 비용이 큰 사이트를 다시 빌드하는 데 필요한 시간을 최소화하는 여러 기법이 있습니다.

증분 렌더링

프로젝트를 작업할 때는 보통 한 번에 한 문서를 반복 수정합니다. 명령줄에서 단일 파일(또는 단일 디렉터리나 파일 목록)을 지정해 증분 렌더링할 수 있습니다.

Terminal
quarto render introduction.qmd
quarto render subdir/

프로젝트의 일부만 렌더링하더라도 관련된 프로젝트 처리 코드는 여전히 실행됩니다. 예를 들어 책 프로젝트에서는 전체 책이 생성됩니다(다른 장은 이전에 렌더링된 버전 사용).

동결

freeze 옵션을 사용하면 전체 프로젝트 렌더링 중 계산 문서를 다시 렌더링하지 않도록 하거나, 소스 파일이 변경될 때만 다시 렌더링하도록 지정할 수 있습니다.

execute:
  freeze: true  # 프로젝트 렌더링 중 다시 렌더링하지 않음
execute:
  freeze: auto  # 소스가 변경될 때만 다시 렌더링

freeze는 전체 프로젝트 렌더링 중 실행 여부를 제어합니다. 단일 문서나 프로젝트 하위 디렉터리를 증분 렌더링하면 코드는 항상 실행됩니다. 예:

Terminal
# 단일 문서 렌더링(항상 코드 실행)
quarto render document.qmd

# 프로젝트 하위 디렉터리 렌더링(항상 코드 실행)
quarto render articles

동결 사용

동결은 협업자가 많거나 오랜 기간에 걸쳐 계산 문서가 많이 쌓인 경우에 주로 사용합니다. 이 경우 사이트를 렌더링할 때 모든 문서를 완전히 재실행하기가 어렵습니다. 일부 문서에 특수하거나 환경 의존적인 요구 사항이 있거나(예: 데이터 소스 접근/인증 필요), 시간이 지나면서 의존성이 깨지기 때문입니다. 동결을 사용하면 언제나 재현 가능하게 사이트를 렌더링할 수 있습니다.

freeze로 실행된 문서의 계산 결과는 _freeze 디렉터리에 저장되며, 필요할 때 문서 렌더링에 재사용됩니다. _freeze 내용을 버전 관리에 포함하면 다른 사람이 프로젝트를 렌더링할 때 동일한 계산 환경을 재현할 필요가 없습니다.

소스 코드 밖의 요소(예: 입력 데이터)가 변경될 때는 프로젝트를 완전히 다시 렌더링하도록 주의해야 합니다. 이전에 동결된 출력은 프로젝트 루트의 _freeze 폴더를 삭제해 제거할 수 있습니다.

가상 환경

freeze를 가상 환경과 함께 사용하면 프로젝트를 각기 다른 의존성을 가진 하위 디렉터리로 나눌 수 있습니다. 이렇게 하면 여러 협업자가 자신이 맡은 문서에 대해 지역화된 의존성을 사용할 수 있으면서도 전체 프로젝트 렌더링은 모든 의존성을 요구하지 않고 가능해집니다.

가상 환경을 만들고 사용하는 방법은 가상 환경 문서를 참고하세요.

다음은 가상 환경과 동결을 함께 사용하는 예시 워크플로입니다.

  1. 프로젝트 실행 옵션에 freeze: true를 추가합니다.

    execute:
  freeze: true

  2. 문서 하위 디렉터리(예: research)를 만들고 그 안에서 가상 환경을 초기화해 사용합니다.

    research/
  document1.qmd
  document2.qmd
  env/
  requirements.txt

  3. 이 하위 디렉터리에서 작업할 때는 문서를 렌더링하기 전에 가상 환경을 활성화합니다. 예:

    Terminal
    cd research
source env/bin/activate
quarto render               # 하위 디렉터리의 모든 파일 렌더링
quarto render document1.qmd  # 단일 파일 렌더링

이 하위 디렉터리 렌더링은 캐시된 freeze 결과를 사용하지 않고, 디렉터리별 가상 환경을 사용해 모든 계산을 다시 수행합니다. 물론 이 디렉터리 안에 하위 디렉터리를 포함할 수 있으며, 해당 문서도 상위 가상 환경을 사용해 렌더링됩니다.

캐시

cache 옵션을 사용해 계산 결과를 캐시할 수 있습니다(R 문서는 knitr cache, Jupyter 문서는 Jupyter Cache, 또는 engine: julia의 내장 지원 사용).

execute:
  cache: true

캐시 무효화는 청크 소스 코드(또는 정의한 다른 캐시 속성) 변경으로 트리거됩니다. 다만 다른 입력(또는 시간)이 충분히 변했다고 판단되면 캐시를 수동으로 갱신해야 할 수 있습니다. 이를 위해 --cache-refresh 옵션으로 개별 파일 또는 전체 프로젝트를 렌더링합니다.

Terminal
quarto render mydoc.qmd --cache-refresh # single doc
quarto render --cache-refresh           # entire project

노트북

.ipynb를 렌더링할 때 Quarto는 기본적으로 노트북 셀을 실행하지 않습니다(노트북을 편집하면서 이미 실행했을 것으로 가정합니다). 셀을 실행하려면 렌더링 시 --execute 플래그를 추가하세요.

Terminal
quarto render notebook.ipynb --execute

노트북 YAML front matter에서 이 동작을 지정할 수도 있습니다.

notebook.ipynb
---
title: "My Notebook"
execute: 
  enabled: true
---

작업 디렉터리

기본적으로 프로젝트 안의 파일을 렌더링할 때 작업 디렉터리는 해당 파일이 있는 디렉터리입니다. 대신 프로젝트의 최상위 디렉터리를 사용하고 싶다면 구성에 execute-dir: project 옵션을 추가할 수 있습니다.

project:
  execute-dir: project

코드 내에서는 QUARTO_PROJECT_DIR 환경 변수를 사용해 현재 실행 중인 Quarto 프로젝트 위치를 항상 확인할 수 있습니다.