Better unexpected sphinx warnings check

[jarrodmillman]

We currently have two places where we run the same check:

• .github/workflows/test.yml
• .github/workflows/prerelease.yml

Also the checks are very general. It may make sense to turn this into a script and to make the checks much more fine-grained.

[jarrodmillman]

In #936, we removed kitchen-sink from the unexpected sphinx warning checks. However, this surprised folks b/c they expected the kitchen-sink to contain broken cross-references. We should check that that is true. If so, we need to see why the aren't generating warnings.

[drammock]

incidentally, I just did this:

$ mamba upgrade --all
$ git switch main
$ git merge --ff-only upstream/main
$ nox --no-reuse-existing-virtualenvs -s docs

and I get lots of warnings:

3 pandas "duplicate object description" warnings:

/opt/pydata-sphinx-theme/.nox/docs/lib/python3.9/site-packages/pandas/core/frame.py:docstring of pandas.core.frame.DataFrame.drop:1: WARNING: duplicate object description of pandas.DataFrame.drop, other instance in examples/generated/pandas.DataFrame.drop, use :noindex: for one of them
/opt/pydata-sphinx-theme/.nox/docs/lib/python3.9/site-packages/pandas/core/frame.py:docstring of pandas.core.frame.DataFrame.groupby:1: WARNING: duplicate object description of pandas.DataFrame.groupby, other instance in examples/generated/pandas.DataFrame.groupby, use :noindex: for one of them
/opt/pydata-sphinx-theme/.nox/docs/lib/python3.9/site-packages/pandas/core/series.py:docstring of pandas.Series.array:1: WARNING: duplicate object description of pandas.Series.array, other instance in examples/generated/pandas.Series.array, use :noindex: for one of them

lots of warnings about missing gallery images (can be safely ignored, as I didn't run the playwright script first)

/opt/pydata-sphinx-theme/docs/examples/gallery.md:14: WARNING: image file not readable: _static/gallery/pandas.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:25: WARNING: image file not readable: _static/gallery/numpy.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:36: WARNING: image file not readable: _static/gallery/scipy.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:47: WARNING: image file not readable: _static/gallery/bokeh.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:58: WARNING: image file not readable: _static/gallery/cupy.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:69: WARNING: image file not readable: _static/gallery/pyvista.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:80: WARNING: image file not readable: _static/gallery/mne-python.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:91: WARNING: image file not readable: _static/gallery/networkx.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:102: WARNING: image file not readable: _static/gallery/fairlearn.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:113: WARNING: image file not readable: _static/gallery/jupyter_book.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:124: WARNING: image file not readable: _static/gallery/binder.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:135: WARNING: image file not readable: _static/gallery/jupyter.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:146: WARNING: image file not readable: _static/gallery/megengine.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:157: WARNING: image file not readable: _static/gallery/feature-engine.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:168: WARNING: image file not readable: _static/gallery/arviz.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:179: WARNING: image file not readable: _static/gallery/sepal.png
/opt/pydata-sphinx-theme/docs/examples/gallery.md:190: WARNING: image file not readable: _static/gallery/enoslib.png

3 more "duplicate object description" warnings

/opt/pydata-sphinx-theme/.nox/docs/lib/python3.9/site-packages/pandas/core/frame.py:docstring of pandas.core.frame.DataFrame.drop:1: WARNING: duplicate object description of pandas.DataFrame.drop, other instance in demo/generated/pandas.DataFrame.drop, use :noindex: for one of them
/opt/pydata-sphinx-theme/.nox/docs/lib/python3.9/site-packages/pandas/core/frame.py:docstring of pandas.core.frame.DataFrame.groupby:1: WARNING: duplicate object description of pandas.DataFrame.groupby, other instance in demo/generated/pandas.DataFrame.groupby, use :noindex: for one of them
/opt/pydata-sphinx-theme/.nox/docs/lib/python3.9/site-packages/pandas/core/series.py:docstring of pandas.Series.array:1: WARNING: duplicate object description of pandas.Series.array, other instance in demo/generated/pandas.Series.array, use :noindex: for one of them

A bunch of autosummary warnings from our urllib.parse example

/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.DefragResult:28: WARNING: autosummary: stub file not found 'urllib.parse.DefragResult.count'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.DefragResult:28: WARNING: autosummary: stub file not found 'urllib.parse.DefragResult.index'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.DefragResultBytes:28: WARNING: autosummary: stub file not found 'urllib.parse.DefragResultBytes.count'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.DefragResultBytes:28: WARNING: autosummary: stub file not found 'urllib.parse.DefragResultBytes.index'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.ParseResult:54: WARNING: autosummary: stub file not found 'urllib.parse.ParseResult.count'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.ParseResult:54: WARNING: autosummary: stub file not found 'urllib.parse.ParseResult.index'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.ParseResultBytes:54: WARNING: autosummary: stub file not found 'urllib.parse.ParseResultBytes.count'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.ParseResultBytes:54: WARNING: autosummary: stub file not found 'urllib.parse.ParseResultBytes.index'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.SplitResult:50: WARNING: autosummary: stub file not found 'urllib.parse.SplitResult.count'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.SplitResult:50: WARNING: autosummary: stub file not found 'urllib.parse.SplitResult.index'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.SplitResultBytes:50: WARNING: autosummary: stub file not found 'urllib.parse.SplitResultBytes.count'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.SplitResultBytes:50: WARNING: autosummary: stub file not found 'urllib.parse.SplitResultBytes.index'. Check your autosummary_generate setting.
/opt/miniforge3/envs/pst/lib/python3.9/urllib/parse.py:docstring of urllib.parse.quote:14: ERROR: Unexpected indentation.

looking for now-outdated files... none found
pickling environment... done

A couple of "not in the TOCTree" warnings

checking consistency... /opt/pydata-sphinx-theme/docs/demo/generated/pandas.DataFrame.drop.rst: WARNING: document isn't included in any toctree
/opt/pydata-sphinx-theme/docs/demo/generated/pandas.DataFrame.groupby.rst: WARNING: document isn't included in any toctree
/opt/pydata-sphinx-theme/docs/demo/generated/pandas.Series.array.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] user_guide/web-components                                                                                                                                                                                                                                                                            

...and finally, the warnings that spawned #936

/opt/pydata-sphinx-theme/.nox/docs/lib/python3.9/site-packages/pandas/core/frame.py:docstring of pandas.core.frame.DataFrame.groupby:42: WARNING: undefined label: 'groupby.transform'
/opt/pydata-sphinx-theme/.nox/docs/lib/python3.9/site-packages/pandas/core/frame.py:docstring of pandas.core.frame.DataFrame.groupby:42: WARNING: undefined label: 'groupby.transform'

but (surprisingly!) no warnings from the kitchen_sink file!