TST/DOC: fix build-docs and codecov failures from the PyVista animations

[Gui-FernandesBR]

Pull request type

• Code maintenance (refactoring, formatting, tests)
• ReadMe, Docs and GitHub updates

Checklist

• Tests for the changes have been added (if needed)
• Docs have been reviewed and added / updated
• Lint (ruff check / ruff format --check / pylint) has passed locally
• Relevant tests (tests/unit/test_plots.py, tests/integration/test_plots.py) have passed locally (off screen, under Xvfb)
• CHANGELOG.md has been updated (if relevant)

Current behavior

The develop -> master sync (#1068) is red on two checks, both caused by the new PyVista 3D flight animation subsystem in rocketpy/plots/flight_plots.py:

• build-docs (3.12) fails. The docs job builds Sphinx with -W (warnings treated as errors) and emits a single warning:

  rocketpy/plots/flight_plots.py:docstring of ...animate_trajectory:
  WARNING: invalid value set (missing closing brace):
  {"speed", "mach", "dynamic_pressure", "acceleration",
  

  The color_by parameter used the numpydoc {...} "set of values" syntax split across two physical lines, which numpydoc cannot parse.

• codecov/patch (74.77%) and codecov/project fail. The animation subsystem (~1000 new lines: scene builders, geometry/telemetry helpers, option parsing, the render loop) was only exercised by one minimal off-screen smoke test, so most of it counted as uncovered — dropping project coverage ~1% below the base and patch coverage below the 5% threshold.

New behavior

• Docs: rewrote the color_by type as a single-line prose description (str | bool | None, one of ...), so numpydoc parses it cleanly and the -W build succeeds. Verified with numpydoc.docscrape.FunctionDoc that the docstring now parses without warnings.

• Coverage: added tests instead of suppressing coverage, so the logic is genuinely checked:

  • New unit tests in tests/unit/test_plots.py for the render-independent helpers: quaternion → rotation matrix, safe unit vector, color scheme / override validation, scalar metadata, polyline & dashed-polyline builders, direction arrow, camera-path interpolation and camera-mode updates, chart-cursor updates, background palette (day/night/explicit) and altitude blending, _animation_options defaults and every validation error, ground-image bounds (ENU + lat/lon + errors), model-path / time-range validation, position/velocity/wind/scalar samplers, event markers, phase labels and telemetry panels.
  • Extended the off-screen integration tests in tests/integration/test_plots.py to drive both animations with the full overlay set (color-by, kinematic/attitude charts, subrocket point, camera tracking, CP/CM stability markers, playback controls) and to cover the deterministic GIF export path.

  Locally this raises flight_plots.py animation coverage from ~286 missing lines to ~88 (the residual being the genuinely interactive timer/widget callbacks that only fire in a live event loop), which brings patch coverage to ~88% and project coverage above the base.

No production behavior changes — only a docstring edit and new tests.

Breaking change

• No

Additional information

The animation methods require a display; the new integration tests render off screen (backend="none", off_screen=True) exactly like the existing smoke test and are guarded with pytest.importorskip("pyvista") / pytest.importorskip("imageio"). CHANGELOG.md intentionally left untouched per discussion in #1068.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VW2VidZmPd93dd8xW8BX2J

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.18%. Comparing base (ce3342f) to head (e0ff281).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1069      +/-   ##
===========================================
+ Coverage    80.85%   82.18%   +1.32%     
===========================================
  Files          122      122              
  Lines        16355    16355              
===========================================
+ Hits         13224    13441     +217     
+ Misses        3131     2914     -217     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.