Refresh python requirements and add instructions (#238)

It's been a while since we updated `requirements_lock.txt`, and we've
accumulated four Dependabot alerts (7, 8, 9, and 10).  I took the
opportunity to write down all the steps we should take when doing this
update.  Naturally, I also performed all of those steps.

For the A/B website comparison, I found 3 differences:

- Menu alignment has been tweaked on a few pages to reduce word wrapping
- Tab headers are underlined
- Mermaid diagram arrowheads are thicker

For testing `mike`, the suggested workflow actually caught some breaking
changes for our monkey patch code.  I therefore made the first step to
simply directly check the patched APIs.

The new version of mkdocs now warns about anchors, and it caught an
incorrect anchor in a recent doc update.  I've fixed that as well.

REQUIREMENTS_LOCK.md

@@ -0,0 +1,67 @@
+# Updating `requirements_lock.txt`
+
+This file explains how to update the `requirements_lock.txt` file, and how to test those updates.  (We
+need to refresh it periodically.)
+
+## Performing the update
+
+Run this command:
+
+```sh
+bazel run //:requirements.update -- --upgrade
+```
+
+## Testing the update
+
+The main thing the requirements file affects is the documentation website.  We mainly pay attention
+to changes in the desired packages, listed in `requirements.in`; keeping track of changes in
+automatically pulled dependencies would be overwhelming and untenable.
+
+### Read the release notes
+
+- Look at the diff for `requirements_lock.txt` to get the old and new version number for every
+  package listed in `requirements.in`.
+- Read the release notes for every release that occurred since the previous version.
+- Look out for breaking changes, and figure out how to test any that you see.
+
+### A/B compare the website
+
+- Run `au-docs-serve` to generate the latest version of the doc website; load it in a new window.
+- In another tab, open <https://aurora-opensource.github.io/au/main/>.
+- Tab back and forth to look for any changes.
+      - Page down once on each page, and repeat.
+      - At the end of the page, click the link to the next page, and repeat.
+- Keep track of whatever changes you see.
+
+You don't need to go through the _entire_ website, but visit enough pages to be satisfied that it's
+representative.
+
+### Make sure `mike` still works
+
+`mike` is how we generate our versioned documentation.
+
+First, visit the source code for the version of `mike` in the new release.  (You can find this on
+their [releases](https://github.com/jimporter/mike/releases) page; click the tag link on the left
+side to browse the code.)  Double check the functions that we monkey patch in `mike_bin.py`, to make
+sure their interfaces and/or implementations are still up to date.
+
+Next, make sure that our monkey patched version of mike works.  Here's a suggested sequence.
+
+```sh
+# Create a new version of the docs, named "temp-test".
+#
+# NOTE: this will not deploy anything remotely.
+bazel run //:mike -- deploy temp-test
+
+# View the list of versions: make sure "temp-test" is in the list.
+bazel run //:mike -- list
+
+# Serve the documentation website.  (Open it in a browser; play around.)
+bazel run //:mike -- serve
+
+# Delete the testing version.
+bazel run //:mike -- delete temp-test
+
+# Nitpicky cleanup: don't want this in our public git history.
+git branch -f gh-pages origin/gh-pages
+```

docs/discussion/idioms/unit-slots.md

@@ -60,7 +60,7 @@ they have two advantages that make them easier to read:
 ### Other expressions
 
 There are other monovalue types that would feel right at home in a unit slot.  We typically support
-those too!  Key examples include [unit symbols](../../reference/unit.md#unit-symbols) and
+those too!  Key examples include [unit symbols](../../reference/unit.md#symbols) and
 [constants](../../reference/constant.md).  Expand the block below to see a worked example.
 
 ??? example "Example: using unit symbols and constants in unit slots"

docs/reference/unit.md

@@ -517,7 +517,7 @@ feet(6).in(Inches{});
 ```
 
 The underlined arguments are all unit slots.  The kinds of things that can be passed here include
-a `QuantityMaker` for a unit, a [constant](./constant.md), a [unit symbol](#unit-symbols), or simply
+a `QuantityMaker` for a unit, a [constant](./constant.md), a [unit symbol](#symbols), or simply
 a unit type itself.
 
 The use case for this trait is to _implement_ the unit slot argument for a function.

mike_bin.py

@@ -30,41 +30,42 @@
 
 def override_version():
     """Override mike's native logic for retrieving the version."""
+    # Original code:
+    #    output = subprocess.run(
+    #        ['mkdocs', '--version'],
+    #        check=True, stdout=subprocess.PIPE, universal_newlines=True
+    #    ).stdout.rstrip()
+    #    m = re.search('^mkdocs, version (\\S*)', output)
+    #    return m.group(1)
+    # Changed version (reformatted with Black):
     output = subprocess.run(
         ["update_docs", "--version"],
         check=True,
         stdout=subprocess.PIPE,
         universal_newlines=True,
     ).stdout.rstrip()
-
-    # Original line:
-    #
-    #    m = re.search('^mkdocs, version (\\S*)', output)
-    #
-    # Changed version:
     m = re.search("^\\S+, version (\\S*)", output)
-
     return m.group(1)
 
 
-def override_build(config_file, version, verbose=True):
+def override_build(config_file, version, *, quiet=False, output=None):
     """Override mike's native logic for building the docs."""
     # Original line:
-    #
-    #     command = (
-    #         ['mkdocs', 'build', '--clean'] +
-    #         (['--config-file', config_file] if config_file else [])
-    #     )
-    #
+    #    command = (
+    #        ['mkdocs'] + (['--quiet'] if quiet else []) + ['build', '--clean'] +
+    #        (['--config-file', config_file] if config_file else [])
+    #    )
     # Changed version (reformatted with Black):
-    command = ["update_docs", "build", "--clean"] + (
-        ["--config-file", config_file] if config_file else []
+    command = (
+        ["update_docs"]
+        + (["--quiet"] if quiet else [])
+        + ["build", "--clean"]
+        + (["--config-file", config_file] if config_file else [])
     )
 
     env = os.environ.copy()
     env[docs_version_var] = version
 
-    output = None if verbose else subprocess.DEVNULL
     subprocess.run(command, check=True, env=env, stdout=output, stderr=output)