[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

@@ -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
+        - docs

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/ \

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::