Using Quarto with ReadTheDocs

[mfisher87]

Description

I normally deploy Quarto sites with GitHub Pages, but for some projects, I want to use ReadTheDocs especially for the "pull request preview" feature. I've been around the block a few times on pull request previews, and now for my sanity I just settle for ReadTheDocs and cross my fingers that previews become a first-class feature in GitHub Pages some day soon.

I feel the solution I landed on for this was quite hacky, so I'd love to see suggestions to improve it! I'm working on setting up a new RTD site, and of course will use Quarto 1.4 this time. Maybe if we clean this up we can add a page in the docs about using Quarto with RTD? 🚀

Here's my RTD config: https://github.com/nsidc/usaon-benefit-tool/blob/4cab422abd4ce26e7cf60320cb10a1781db97f44/.readthedocs.yaml

[mlysy]

I would also have a use-case for this! From the readthedocs documentation, there's an example of installing dependencies with uv, where uv itself is installed via asdf:

# .readthedocs.yaml
version: 2

sphinx:
   configuration: docs/conf.py

build:
   os: ubuntu-24.04
   tools:
      python: "3.13"
   jobs:
      pre_create_environment:
         - asdf plugin add uv
         - asdf install uv latest
         - asdf global uv latest
      create_environment:
         - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
      install:
         - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs

It seems that this install job could be adapted to Quarto if it were available as an asdf plugin, so I created one here. I haven't tried it yet on readthedocs though...

[mfisher87]

I totally forgot about this post :) These days I use Pixi to install the Quarto conda package and build from there. Looks like:

https://github.com/geojupyter/geojupyter.org/blob/59e1b1089b74142a315be060fb1b8da816ed7cb2/.readthedocs.yaml

[mlysy]

Very cool! Thanks for sharing :)