[CLEANUP] Post-0.5.0 tidy — dtype gap, dead code, CLI docs from parser, doc refresh

[eleanorfrajka]

Summary

Low-risk cleanup with no behaviour change to any committed output or fixture: a timedelta dtype-passthrough fix in find_best_dtype, removal of the dead proc_machine report-context key, a warning in place of a silent exception swallow in the grid report, the CLI reference now generated from the argument parser (via sphinx-argparse) instead of hand-maintained flag tables, and a CONTRIBUTING/README refresh. The CF current_direction standard_name rename initially scoped here was pulled out to ship with 0.6.0 — it is an output-attribute change.

What's changed

• find_best_dtype now passes through timedelta64 (dtype.kind == "m") alongside datetime64, the same as string/object dtypes. One-character gap; ctdcast's writers/dtypes.py copy has the same gap.
• _isopycnal_ts_panel no longer swallows exceptions silently — it warns with the caught exception before returning None, so a real isopycnal_dataset failure is visible instead of rendering as an "unavailable" stub. Render output is unchanged (still a stub on failure).
• Removed the dead proc_machine report-context key: it was computed in every generator but shown nowhere since the footer dropped the host. Dropped from _mooring, _instrument, _stack, _grid, the two now-unused socket imports, the stale _macros.html comment, and the now-pointless socket.gethostname mock in the golden test.
• CONTRIBUTING refresh: architecture table (report/→reports/, added writers/ and inspect.py); ruff format in the workflow step; canonical-units convention; the real report plot-style mechanism; real-fixture and golden-test rules; and a Scope section (fixed output contract vs. method choices open to alternatives). One-sentence scope added to the README (naming only caldip and ctdcast as the adjacent raw-processing siblings).
• CLI reference generated from the parser: cli_reference.rst now uses .. argparse:: blocks per subcommand (via sphinx-argparse, added to the docs extra and conf.py), so the flag lists cannot drift from build_parser(). All prose, stage descriptions, "output created" sections and examples stay hand-written. Two help= strings enriched so nothing is lost (--pdf reading order; --array reworded to drop a bare * that RST read as emphasis). This corrected a stale --stage default ("1 2" → the real "1 2 3").

Breaking changes

None. (The current_direction CF standard_name rename, an output-attribute change, was deferred to the 0.6.0 cycle and is not in this PR.)

Tests

793 unit tests pass (tests/unit, excluding slow/local/seasenselib); 28 CLI tests pass; ruff clean; golden report tests green. The docs build was verified with sphinx-argparse installed — cli_reference renders all eight subcommands with no warnings (only expected cross-doc :doc: links in isolation). No new test added — find_best_dtype's timedelta path and the isopycnal warn are covered by existing report/dtype tests; the proc_machine removal is a pure deletion of unrendered context.

Notes

The --help output changes slightly: the generated CLI reference makes the parser's help= strings the documentation, so two were enriched (--pdf reading order, --array rewording). The sphinx-argparse dependency is docs-only (in the docs/dev extras, not runtime).

[Copilot]

🟡 Changes recommended

Add regression coverage for the timedelta and warning paths and correct the noted contributor documentation wording.

3 open findings

• Add warning test for failed isopycnal rendering · New
• Add regression test for timedelta dtype passthrough · New
• Clarify side-effect claims for file readers and writers · New

What changed in this PR

Post-0.5.0 cleanup covering dtype preservation, report context removal, warning visibility, and documentation updates.

Changes:

• Preserve timedelta64 dtypes and warn on isopycnal rendering failures.
• Remove obsolete proc_machine context and related test/template code.
• Generate CLI documentation from the parser and refresh project guidance.

File	Reviewed changes
tests/​unit/​test_report_golden.py	Removed obsolete hostname mocking.
README.md	Clarified project scope and sibling tools.
pyproject.toml	Added the documentation dependency.
oceanarray/​utilities.py	Added timedelta dtype passthrough; a direct regression test is requested.
oceanarray/​reports/​templates/​_macros.html	Removed stale context documentation.
oceanarray/​reports/​_stack.py	Removed obsolete report context.
oceanarray/​reports/​_mooring.py	Removed hostname context generation.
oceanarray/​reports/​_instrument.py	Removed hostname context generation.
oceanarray/​reports/​_grid.py	Added failure warnings; a focused warning-path test is requested.
oceanarray/​cli.py	Improved CLI help text.
docs/​source/​conf.py	Enabled sphinx-argparse.
docs/​source/​cli_reference.rst	Generated command options from the parser.
CONTRIBUTING.md	Refreshed architecture, scope, workflow, and testing guidance; two wording corrections are requested.

🧠 Review effort: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.