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.
This commit is contained in:
Ross Patterson 2025-08-29 14:33:32 -07:00
parent 5762d34891
commit d3fe155b72
No known key found for this signature in database
GPG key ID: 2EFF7CCE6828E359

View file

@ -63,7 +63,8 @@ executable: clean
mv dist/ytdl-sub dist/ytdl-sub${EXEC_SUFFIX}
docs:
REGENERATE_DOCS=1 pytest tests/unit/docgen/test_docgen.py
sphinx-build --fail-on-warning --nitpicky -b html docs/source/ docs/build/
sphinx-build --write-all --fail-on-warning --nitpicky -b html \
"./docs/source/" "./docs/build/"
clean:
rm -rf \
.pytest_cache/ \