From d3fe155b72f31a59e6ae4eb9fa948da4cbf9ea46 Mon Sep 17 00:00:00 2001 From: Ross Patterson Date: Fri, 29 Aug 2025 14:33:32 -0700 Subject: [PATCH] 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. --- Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index d51d267c..0be80e53 100644 --- a/Makefile +++ b/Makefile @@ -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/ \