321556ecf7
* ci(docs): RTD Sphinx warnings false successes Use the same options on readthedocs.com that we use locally to fail on all warnings, mostly to better catch stale cross references. * docs(usage): Yet another stale Sphinx cross ref I confirmed the previous RTD CI fix in the previous commit by pushing it to a draft PR before pushing this change and the RTD action failed with the warning this commit fixes. After pushing this commit, the RTD action succeeded. * build(docs): Sphinx stale cross refs false success I figured out why I kept getting warnings for broken Sphinx cross-refs *after* the changes that caused them have already been merged, changes I know I ran `$ make docs` for before pushing. The issue is that by default Sphinx only builds changed files for faster iterations while editing, but it only catches broken cross-refs when it builds files. So if changing, for example, a section name in one page that is referenced from another page that you do *not* change, then the warning will be missed until something changes that other page, such as a pull or rebase. I considered adding a separate `./Makefile` target for incremental builds in the inner loop of making changes. But I opted to just remove the `--write-all` CLI option locally while editing in the inner loop, because the uncommitted change will remind me to revert it and run a full rebuild before pushing.
18 lines
280 B
YAML
18 lines
280 B
YAML
version: 2
|
|
|
|
build:
|
|
os: "ubuntu-22.04"
|
|
tools:
|
|
python: "3.10"
|
|
|
|
sphinx:
|
|
configuration: docs/source/conf.py
|
|
fail_on_warning: true
|
|
|
|
python:
|
|
install:
|
|
- requirements: docs/source/requirements.txt
|
|
- method: pip
|
|
path: .
|
|
extra_requirements:
|
|
- docs
|