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:
parent
5762d34891
commit
d3fe155b72
1 changed files with 2 additions and 1 deletions
3
Makefile
3
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/ \
|
||||
|
|
|
|||
Loading…
Reference in a new issue