.readthedocs.yaml

# Read the Docs build configuration for VFBquery.
#
# https://docs.readthedocs.io/en/stable/config-file/v2.html
#
# The docs are Sphinx + MyST, sourced from `docs/`. Most of the pages already
# existed as plain markdown in this repo before the site did — `docs/conf.py`
# copies the repo-root ones (README, CACHING, RELEASING, schema, …) into
# `docs/_root/` at build time rather than moving them, because README.md is
# regenerated by the `examples` workflow and the others are read directly on
# GitHub. Nothing here edits a source file.
#
# The same build runs in CI (see `docs/ci/docs.yml`), so a warning shows up on
# the pull request rather than as a red badge on the docs site after merge.

version: 2

build:
  os: ubuntu-24.04
  tools:
    python: "3.11"

sphinx:
  configuration: docs/conf.py
  # A broken cross-reference or a page missing from the toctree is a bug in the
  # docs, not a cosmetic issue: the whole point of the site is that a reader can
  # follow a link. Failing the build is what keeps that true.
  fail_on_warning: true

python:
  install:
    - requirements: docs/requirements.txt
    # The client is installed for real (it is `requests` + `pandas` only, so
    # this costs seconds) so that autodoc documents the actual signatures and
    # docstrings rather than a mock. The `vfbquery` server package is NOT
    # installed — it pulls navis/psycopg/vfb_connect, which is exactly the
    # weight the client exists to avoid. `vfbquery.combine` is stdlib-only and
    # is imported straight from `src/` instead; see `autodoc_mock_imports` in
    # docs/conf.py.
    - path: clients/vfbquery-client

formats:
  - pdf
  - htmlzip