docs: fix factual errors, inconsistencies, and typos in the guide (#800)

* fix(docs): correct factual errors and inconsistencies in guide

- packaging tutorial: fix wrong Snell's law output value
- pytest guide: fix inverted skipif condition, strict-markers
  describes markers not fixtures, add missing assert in approx example
- packaging-simple: requires-python upper-cap check is PP004, not PY004
- packaging-compiled: "pure Python project" link pointed at itself
- gha-basic: step output reference missing .outputs.
- gha-wheels: fix mis-indented pull_request trigger; test-groups not
  test-extras
- tasks: fix broken hatch URL (pypa, not pypi)
- style: fix flake8-print URL and stray ) in Ruff v2 badge
- docs: fix corner example link (pointed at astropy)
- data-files: unify peak_spacings directory name
- test tutorial: align dir tree and pytest output with snell example,
  drop incorrect Arrange-Act-Assert reference

Assisted-by: ClaudeCode:claude-opus-4.8

* docs: fix typos and grammar across the guide

- index: repair broken intro sentence
- guides/index: "on for" -> "one for"
- packaging-simple: "you you use"
- coverage: dangling "either with"
- gha-pure: complete trailing sentence about publish guard
- docs: "snipits" -> "snippets", reframe "Popular frameworks" note,
  fix stale linkcheck-handler prose
- mypy: add self to Protocol/impl methods
- backports: importlib.metadata, tomli_w, tzdata
- design: "One alternative is to replace"
- testing: venerable, autospec=True, numpy ndarray
- tutorials/docs: fix {toctree} fence and "interoperate"

* style: pre-commit fixes

* chore: remove commented CLAUDE file

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>

---------

Assisted-by: ClaudeCode:claude-opus-4.8
Signed-off-by: Henry Schreiner <henryfs@princeton.edu>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: henryiii

.gitignore

@@ -183,3 +183,7 @@ Thumbs.db
 # Common editor files
 *~
 *.swp
+
+# Symlink to AGENTS.md
+CLAUDE.md
+.claude/

docs/pages/guides/coverage.md

@@ -137,7 +137,7 @@ your jobs and combine them into one `.coverage` file before running
 
 ##### Manually combining coverage
 
-If you are running in parallel, either with `pytest-xdist`, you can set
+If you are running in parallel, such as with `pytest-xdist`, you can set
 `run.parallel` to `true`, which will add a unique suffix to the coverage file(s)
 produced. If you are using the multiprocessing patch, that also will generate a
 unique suffix for each process launch.

docs/pages/guides/docs.md

@@ -10,14 +10,14 @@ the same format used by GitHub, Wikipedia, and others. This guide covers Sphinx
 and Mkdocs, and uses the modern MyST plugin to get Markdown support.
 
 :::{note} Popular frameworks
-There are other frameworks as well; these often are simpler, but are not as
-commonly used, and have somewhat fewer examples and plugins. They are:
+The two frameworks covered in this guide are the most commonly used in the
+scientific Python community. The main options are:
 
 - [Sphinx](https://www.sphinx-doc.org/en/master/): A popular documentation
   framework for scientific libraries with a history of close usage with
   scientific tools like LaTeX. Examples include
   [astropy](https://docs.astropy.org/en/stable/index_user_docs.html) and
-  [corner](https://docs.astropy.org/en/stable/index_user_docs.html).
+  [corner](https://corner.readthedocs.io).
 - [MkDocs](https://www.mkdocs.org): A from-scratch new documentation system
   based on markdown and HTML. Less support for man pages & PDFs than Sphinx,
   since it doesn't use docutils. Has over
@@ -197,7 +197,7 @@ several good extensions:
 - [`sphinx.ext.napoleon`][] adds support for several common documentation styles
   like numpydoc.
 - `sphinx_autodoc_typehints` handles type hints
-- `sphinx_copybutton` adds a handle little copy button to code snipits.
+- `sphinx_copybutton` adds a handy little copy button to code snippets.
 
 We are including both possible file extensions. We are also avoiding some common
 file patterns, just in case.
@@ -602,9 +602,9 @@ some conditional installs based on arguments (sphinx-autobuild is only needed if
 serving). It does an editable install of your package so that you can skip the
 install steps with `-R` and still get updated documentation.
 
-Then there's a dedicated handler for the 'linkcheck' builder, which just checks
-links, and doesn't really produce output. Finally, we collect some useful args,
-and run either the autobuild (for `--serve`) or regular build. We could have
+The `-b` argument selects the builder, so you can pass `-b linkcheck` to just
+check links, for example. Finally, we collect some useful args, and run either
+the autobuild (when interactive) or a regular build. We could have
 just added `python -m http.server` pointing at the built documentation, but
 autobuild will rebuild if you change a file while serving.
 :::

docs/pages/guides/gha_basic.md

@@ -226,9 +226,9 @@ actions have outputs, and bash actions can manually write to output:
 ```
 
 You can now refer to this step in a later step with
-`${{ steps.someid.something }}`. You also can get it from another job by using
-`${{ needs.<jobname>.outputs.something }}`. The `toJson()` function is useful
-for inputting JSON - you can even generate matrices dynamically this way!
+`${{ steps.someid.outputs.something }}`. You also can get it from another job by
+using `${{ needs.<jobname>.outputs.something }}`. The `toJson()` function is
+useful for inputting JSON - you can even generate matrices dynamically this way!
 
 #### Pretty output
 

docs/pages/guides/gha_pure.md

@@ -46,7 +46,7 @@ jobs:
 This will run when you manually trigger a build ([`workflow_dispatch`][]), or
 when you publish a release. Later, we will make sure that the actual publish
 step requires the event to be a publish event, so that manual triggers (and
-branches/PRs, if those are enabled).
+branches/PRs, if those are enabled) do not publish to PyPI.
 
 If you want tags instead of releases, you can add the `on: push: tags: "v*"` key
 instead of the releases - however, _please_ remember to make a GitHub release of

docs/pages/guides/gha_wheels.md

@@ -24,9 +24,9 @@ on:
   release:
     types:
       - published
-    pull_request:
-      paths:
-        - .github/workflows/cd.yml
+  pull_request:
+    paths:
+      - .github/workflows/cd.yml
 ```
 
 This will run on releases. If you use a develop branch, you could include
@@ -55,7 +55,7 @@ build-verbosity = 1
 ```
 
 The build frontend is set to `build[uv]`, which is faster than the default build
-backend; you just need uv installed, but that's easy to do. The `test-extras`
+backend; you just need uv installed, but that's easy to do. The `test-groups`
 will cause the pip install to use the dependency-group(s) specified. The
 `test-command` will use pytest to run your tests. You can also set the build
 verbosity (`-v` in pip) if you want to.

docs/pages/guides/index.md

@@ -19,10 +19,10 @@ which should help in ensuring a consistent developer and user experience when
 working with distribution.
 
 A section on CI follows, with a [general setup guide][gha_basic], and then two
-choices for using CI to distribute your package, on for [pure Python][gha_pure],
-and one for [compiled extensions][gha_wheels]. You can read about setting up
-good tests on the [pytest page][pytest], with [coverage][]. There's also a page
-on setting up [docs][], as well.
+choices for using CI to distribute your package, one for
+[pure Python][gha_pure], and one for [compiled extensions][gha_wheels]. You can
+read about setting up good tests on the [pytest page][pytest], with
+[coverage][]. There's also a page on setting up [docs][], as well.
 
 :::{tip} New project template
 Once you have completed the guidelines, there is a

docs/pages/guides/mypy.md

@@ -127,7 +127,7 @@ from typing import Protocol
 
 
 class Duck(Protocol):
-    def quack() -> str: ...
+    def quack(self) -> str: ...
 ```
 
 Now any object that can "quack" (and return a string) is a Duck. We can even add
@@ -145,7 +145,7 @@ we can write a duck implementation and test it like this:
 
 ```python
 class MyDuck:
-    def quack() -> str:
+    def quack(self) -> str:
         return "quack"
 ```
 

docs/pages/guides/packaging_compiled.md

@@ -44,7 +44,7 @@ The most exciting developments have been new native build backends:
 
 :::{note}
 You should be familiar with [packing a pure Python
-project](pages/guides/packaging-compiled) - the metadata
+project](pages/guides/packaging-simple) - the metadata
 configuration is the same.
 :::
 There are also classic setuptools plugins:

docs/pages/guides/packaging_simple.md

@@ -94,7 +94,7 @@ build-backend = "setuptools.build_meta"
 ```
 
 For `requires-python`, you should specify the minimum you require, and you
-should not put an upper cap on it {rr}`PY004`, as this field is used to
+should not put an upper cap on it {rr}`PP004`, as this field is used to
 back-solve for old package versions that pass this check, allowing you to safely
 drop Python versions.
 
@@ -109,7 +109,7 @@ the installed version - this obviously tends to break if you build parts of the
 library or if you access package metadata.
 
 This sadly is not part of the standard metadata in `[project]`, so it depends on
-what backend you you use. Hatchling, Flit, PDM, and setuptools use automatic
+what backend you use. Hatchling, Flit, PDM, and setuptools use automatic
 detection.
 
 If you don't match your package name and import name (which you should except