Build online docs (RTD) with -W and dependencies

This configures Read the Docs builds to be more like local builds
in two ways:

- Pass "-W", as is done in a local build with "make -C doc html",
  so that if there are broken references, the build fails.

- Install dependencies. This configures the Python environment, via
  the python.install key, so that RTD builds install requirements.

More specifically on dependency installation, it does two things:

1. The equivalent of "pip install .", which installs the project
   and its dependencies (though not any extras). This includes the
   gitdb dependency, which is needed to import GitPython's git
   module to populate sections in the API Reference page (#1840).

2. The equivalent of "pip install -r doc/requirements.txt", which
   installs the additional Sphinx-related dependencies used when
   building documentation locally.

Installing Sphinx-related dependencies is useful for three reasons:

a. Least importantly, it should increase consistency between remote
   (RTD) and local documentation builds.

b. It may be needed to avoid warnings that are not being fixed at
   this time, while still allowing the build to succeed with the
   "-W" option (see above on that change) that causes failure for
   immediately addressable problems. The effect of newer versions
   of Sphinx carrying a few extra hard-to-fix warnings for
   GitPython is noted in #1802 (and is why they are not upgraded
   in #1803).

c. One of the documentation build dependencies listed in
   doc/requirements.txt is sphinx_rtd_theme. In 634151a (for #1794)
   the line specifying this theme was commented out, since it
   apparently broke in the build. This may allow it to be used
   again (or can be replaced with another custom theme if desired).

This also reenables the sphinx_rtd_theme theme disabled in 634151a.

Finally, this makes minor changes to .readthedocs.yml's comments
and formatting so the comments are accurate for GitPython details
and so the file is formatted in the same style as other YAML here.

Author: EliahKagan

.readthedocs.yaml

@@ -4,7 +4,7 @@
 # Required
 version: 2
 
-# Set the OS, Python version and other tools you might need
+# Set the OS, Python version and other tools you might need.
 build:
   os: ubuntu-22.04
   tools:
@@ -14,22 +14,24 @@ build:
     # rust: "1.70"
     # golang: "1.20"
 
-# Build documentation in the "docs/" directory with Sphinx
+# Build documentation in the "doc/" directory with Sphinx.
 sphinx:
   configuration: doc/source/conf.py
   # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
   # builder: "dirhtml"
   # Fail on all warnings to avoid broken references
-  # fail_on_warning: true
+  fail_on_warning: true
 
-# Optionally build your docs in additional formats such as PDF and ePub
+# Optionally build your docs in additional formats such as PDF and ePub.
 # formats:
-#   - pdf
-#   - epub
+# - pdf
+# - epub
 
 # Optional but recommended, declare the Python requirements required
-# to build your documentation
+# to build your documentation.
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#   install:
-#     - requirements: docs/requirements.txt
+python:
+  install:
+  - method: pip
+    path: .
+  - requirements: doc/requirements.txt

doc/source/conf.py

@@ -93,7 +93,7 @@
 # Options for HTML output
 # -----------------------
 
-# html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_rtd_theme"
 html_theme_options = {}
 
 # The name for this set of Sphinx documents.  If None, it defaults to