readthedocs.yaml or Admin UI for Build Configuration Precedence?
0 reputation · 03 Feb 2022, 17:04 UTC
Goal: choose a single source of truth for build configuration so that Python version and install steps are applied consistently, while still allowing immediate adjustments without a commit.
Read the Docs supports declarative configuration via readthedocs.yaml in the repository and imperative configuration through the project admin UI. The YAML file is versioned with the docs source; UI settings can be changed without a commit. The unresolved behavior is precedence: when both define the same setting, which one wins for a given platform release? Public documentation does not guarantee a stable order, and the outcome may differ by plan or version.
The constraint is reproducibility across builds versus operational flexibility. If the YAML file is authoritative, UI changes may be silently ignored or overridden. If the UI is authoritative, the repository configuration becomes advisory.
- For a given Read the Docs release, does
readthedocs.yamloverride admin UI settings for Python version and install steps, or vice versa? - How can a project confirm which source is in effect without relying on a successful build outcome?
- Does precedence vary between public and private projects or across plans?