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}
|
mv dist/ytdl-sub dist/ytdl-sub${EXEC_SUFFIX}
|
||||||
docs:
|
docs:
|
||||||
REGENERATE_DOCS=1 pytest tests/unit/docgen/test_docgen.py
|
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:
|
clean:
|
||||||
rm -rf \
|
rm -rf \
|
||||||
.pytest_cache/ \
|
.pytest_cache/ \
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue