Add modern type hints and reST docstrings throughout PGraph.py

[petercorke]

Summary

• Type-hints every public and most private members using PEP 604 union syntax (X | Y) and numpy.typing (ArrayLike/NDArray), with matching reST docstrings including .. runblock:: pycon examples that are actually executed at doc build time (via sphinx-pyrunblock, replacing the unmaintained sphinx-autorun).
• Adds mypy as an informational (non-blocking, continue-on-error: true) CI job — the type-hinting pass surfaced a baseline of pre-existing design tensions (Liskov-incompatible overrides, embedded-graph invariants not visible to the type checker) tracked separately, not fixed here.
• Adds sphinx-codeautolink to the docs toolchain, matching spatialgeometry's setup.
• Fixes a couple of small, incidental bugs surfaced while typing touched them: _metricfunc silently swallowing an unrecognized metric string instead of raising, and a missing __iter__/abstract _graphcolor that mypy couldn't otherwise see.
• Fixes a pre-existing docs bug (predates this branch): docs/source/*.rst referenced the module as bare PGraph instead of pgraph.PGraph, a leftover from before the src/pgraph/ layout migration — autodoc couldn't import anything.

No behavioural changes to any bugfix-cluster method (add_vertex, connect, remove, the path_* search methods, the matrix methods) — those are typed together with their fixes in the next PR in this stack, since the fix and the type hints land on the same lines for those methods.

Stacked on #3 (chore/python-3.14-support) — this is the first of four PRs building on top of it: type-hints → rename → bugfixes → iscyclic.

Test plan

• 34/34 existing tests pass unchanged (no behavior change)
• Sphinx docs build cleanly, all runblock examples execute without error
• mypy src/pgraph/PGraph.py runs (informational, not blocking)