From 321556ecf74e8174ef471513cf554a884b40d561 Mon Sep 17 00:00:00 2001
From: Ross Patterson <me@rpatterson.net>
Date: Fri, 29 Aug 2025 15:59:06 -0700
Subject: [PATCH] [DEV] docs: Sphinx stale cross refs false success (#1319)

* 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.
---
 .readthedocs.yaml     | 3 ++-
 Makefile              | 3 ++-
 docs/source/usage.rst | 4 ++--
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 07eb81c9..8bdf9237 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -7,6 +7,7 @@ build:
 
 sphinx:
   configuration: docs/source/conf.py
+  fail_on_warning: true
 
 python:
   install:
@@ -14,4 +15,4 @@ python:
     - method: pip
       path: .
       extra_requirements:
-        - docs
\ No newline at end of file
+        - docs
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/ \
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 2ed28fc2..113e14f8 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -37,7 +37,7 @@ Subscriptions Options
 ---------------------
 
 Download all subscriptions specified in each :doc:`subscriptions file
-<./guides/getting_started/first_sub>`.
+<./guides/getting_started/subscriptions>`.
 
 .. code-block::
 
@@ -60,7 +60,7 @@ Download Options
 ----------------
 
 Download a single subscription in the form of CLI arguments instead of from :doc:`a
-subscriptions file <./guides/getting_started/first_sub>`:
+subscriptions file <./guides/getting_started/subscriptions>`:
 
 .. code-block::