pathfinding: add multi_stop_search Examples, fix sourcecode directive, document NaN impassability (#3651)

[brendancol]

Closes #3651

Doc-only changes to xrspatial/pathfinding.py, found by the documentation sweep:

• Add an Examples section to multi_stop_search (it had none; a_star_search has one). The example runs as written and its waypoint_order / segment_costs / total_cost outputs were verified on this host.
• Fix the ... sourcecode:: python directive in a_star_search's Examples (three dots instead of two, the only occurrence in the codebase; it rendered as literal text instead of a code block).
• Document that NaN surface cells are always impassable regardless of the barriers list, in both public docstrings. The behavior is implemented in _is_not_crossable and pinned by existing tests; only the friction NaN rule was documented before.
• Fix y: str to y : str in a_star_search's Parameters (numpydoc spacing).

No behavior changes. The wrong surface description ("values to bin") and the empty connectivity description are left for #3644, which already tracks them.

Tests: adds test_docstring_params_match_signature (parametrized over both public functions, modeled on the multispectral check with support for grouped x, y : str entries), test_docstring_structure (required sections present, two-dot directive, NaN wording pinned), and test_multi_stop_search_docstring_example (runs the new example and pins its attrs output).

Test plan:

• pytest xrspatial/tests/test_pathfinding.py - 62 passed (57 existing + 5 new)
• Docstring examples for both functions executed as written
• flake8 on both files: no new violations (pre-existing baseline untouched)

Backend coverage: n/a (docstrings and tests only). The backend-support table in a_star_search's docstring was checked against all four backends (numpy, cupy, dask+numpy, dask+cupy) on this host and is accurate as written.

https://claude.ai/code/session_0155N4QGamQVxgpAAPbpQNq4

[brendancol]

PR Review: pathfinding: add multi_stop_search Examples, fix sourcecode directive, document NaN impassability (#3651)

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• xrspatial/pathfinding.py:871-874: the PR fixes the y: str numpydoc spacing but leaves the same defect on the next two entries, snap_start: bool, default=False and snap_goal: bool, default=False. Since the diff already touches this Parameters section for the identical reason, fix all three, not one.

Nits (optional improvements)

• xrspatial/pathfinding.py:1449-1452: the new example pins full-precision float reprs (2.8284271247461903). Rounding in the example would be less brittle if the cost model ever changes. That said, test_multi_stop_search_docstring_example pins the same values, so any drift will surface as a test failure rather than a silently stale docstring. Fine either way.

What looks good

• The new multi_stop_search example was executed and its printed attrs match real output (waypoint_order, segment_costs, total_cost all verified; the waypoints avoid barrier cells).
• The ... sourcecode:: -> .. sourcecode:: fix matches the two-dot form used everywhere else in the codebase.
• The NaN wording matches actual behavior: _is_not_crossable (pathfinding.py:68-77) rejects NaN cells before consulting barriers, and the existing input_data_with_nans tests pin it. The docstring now says so in both the summary and the barriers entries.
• The three new tests follow existing project patterns (test_multispectral.py::test_docstring_params_match_signature, phrase-pinning as in test_proximity.py::test_docstring_states_all_backends), and the params check correctly handles the grouped x, y : str entry.
• Doc-only change; no function behavior touched. The known-wrong surface description and empty connectivity entry are deliberately left to #3644, which already tracks them.

Checklist

• Algorithm matches reference/paper (n/a, docstrings and tests only)
• All implemented backends produce consistent results (backend table re-verified on numpy/cupy/dask+numpy/dask+cupy; unchanged by this PR)
• NaN handling is correct (documentation now matches implementation)
• Edge cases are covered by tests (docstring structure, signature match, example output)
• Dask chunk boundaries handled correctly (n/a)
• No premature materialization or unnecessary copies (n/a)
• Benchmark exists or is not needed (not needed; doc-only)
• README feature matrix updated (n/a, no new functions or backend changes)
• Docstrings present and accurate

[brendancol]

PR Review follow-up (post-fix pass)

Re-checked the branch after 9d9af36.

• Suggestion (snap_start/snap_goal numpydoc spacing): fixed in 9d9af36. All three Parameters entries in a_star_search now use the name : type form; grep -n '^\s*\w\+:' over the docstring finds no remaining offenders.
• Nit (full-precision floats in the example): kept as is. Pinning real printed output matches the existing precedent (allocation's example and test_allocation_docstring_example), and test_multi_stop_search_docstring_example fails loudly if the values ever drift.

Docstring tests still pass (5/5), no new flake8 findings. Nothing further from me.