Sphinx docs cleanup: dead config, docstring warnings, and warning-gating

[levon003]

Follow-up cleanup items from a review of our Sphinx docs setup. The CI gaps (PR docs-build validation + uv caching) are handled separately in #116; this issue tracks the rest, to be done after CI is sorted so we can gate on a clean build.

1. Remove dead linkcode_resolve boilerplate (docs/conf.py)

linkcode_resolve (lines ~97–150) is copied from matplotlib's conf.py: it guards on fn.startswith(("matplotlib/", "mpl_toolkits/")) and emits github.com/matplotlib/... URLs, so for FlexEval it always returns None. The working [source] links in the output come from sphinx.ext.viewcode (they point at _modules/...), not sphinx.ext.linkcode. So the linkcode extension + the ~55-line function do nothing.

Fix: drop sphinx.ext.linkcode and delete linkcode_resolve (viewcode already covers source links). Alternatively, rewrite it to point at FlexEval's GitHub if we'd prefer GitHub source links over the bundled _modules pages.

2. Remove no-op docutils_conf (docs/conf.py)

The docutils_conf dict (lines ~92–94) is never read by Sphinx — it's defined and unreferenced, so its intent (disabling the docutils line-length limit) isn't applied. Remove it, or implement the setting properly.

3. Fix malformed RST in docstrings (25 warnings)

Most of the build's 27 warnings are malformed RST in docstrings, which can also mangle rendered output:

• "Explicit markup ends without a blank line" ×18
• "Definition list ends without a blank line" ×4
• "Block quote ends without a blank line" ×3
• one "Inline emphasis start-string without end-string"

They originate in src/flexeval/configuration/completion_functions.py, src/flexeval/configuration/function_metrics.py, and src/flexeval/compute_metrics.py. (The 27th is a FunctionsCollection pydantic-JSON-schema warning, tracked separately below.)

4. Turn on warning-gating in CI

Once #3 is clean, set SPHINXOPTS="-W --keep-going" for the PR docs-build job so new doc warnings fail the build and don't silently accumulate.

5. Minor: redundant / unused extensions (docs/conf.py)

• napoleon and numpydoc are both enabled (redundant docstring processors; pick one — numpydoc is the one we configure).
• The three matplotlib.sphinxext.* extensions are loaded but there appear to be no .. plot::/figmpl directives that use them.

6. Minor: investigate the FunctionsCollection pydantic JSON-schema warning

WARNING: JSON schema can't be generated for 'flexeval.schema.evalrun_schema.FunctionsCollection' because the following pydantic fields can't be serialized properly: ['functions']. — autodoc-pydantic can't render a schema for this model. Decide whether to fix the field or suppress schema rendering for it.

7. Optional: run make linkcheck

The Makefile catch-all already routes make linkcheck to Sphinx, but it isn't run anywhere. A periodic (or PR) linkcheck would catch dead external links and broken :doc:/:ref: targets.

[levon003]

PR #118 handles items 3 (malformed-RST docstrings), 4 (enable -W --keep-going), and 6 (FunctionsCollection JSON-schema warning, via coerce). It also suppresses the peewee back-reference accessors, which were the source of most of the docstring-adjacent warnings.

Still open after #118: item 1 (dead linkcode_resolve), item 2 (no-op docutils_conf), item 5 (redundant napoleon/numpydoc + unused matplotlib extensions), item 7 (optional make linkcheck).

[levon003]

PR #119 (stacked on #118) handles the remaining items — 1 (dead linkcode_resolve), 2 (no-op docutils_conf), 5 (removed numpydoc + unused matplotlib/sphinx_design/sphinx_tags extensions; kept and wired up inheritance_diagram with class diagrams on the API page), and 7 (make linkcheck documented as a manual step).

With #118 + #119 merged, all items here are addressed and this can be closed.

One leftover noted in #119: the local sphinxext.github extension is also unused, but kept as a self-contained utility for release notes rather than removed.