[FEAT][FIX] Speed up PDF rendering and add report --pdf-dir

[eleanorfrajka]

Summary

Two PDF-report changes. First, a print-CSS fix that cuts combined-PDF render time from ~50s to ~6s by giving tables a fixed layout. Second, a new report --pdf-dir DIR flag that writes each mooring's combined PDF into one shared directory instead of beside its HTML, so PDFs from many moorings collect in one shareable place. The flag is opt-in and changes nothing when unset.

What's changed

PDF render speedup (reports/_pdf.py). The print stylesheet used the default table-layout: auto, which makes WeasyPrint scan every cell to compute intrinsic column widths. A ~7.7 KB one-line seasenselib raw-opaque provenance JSON in an ADCP global-attributes table made that pass pathological — one page took 47s and the whole report ~50s. Setting table-layout: fixed with an explicit width: 100% skips the intrinsic-width scan (columns size from the first row, long values wrap), dropping the report to ~6s. Print-only, so on-screen tables are unaffected; cross-page links still resolve.

report --pdf-dir DIR flag.

• New paths.resolve_pdf_path(mooring, pdf_dir, report_html_dir): with --pdf-dir set, the combined PDF is written to DIR/{mooring}_report.pdf; unset, it stays beside the HTML at report_html_dir/{mooring}_report.pdf. The resolver is pure — it creates no directory — so the dry-run preview stays side-effect-free.
• cmd_report wires the resolver into both the dry-run preview and the real PDF branch, so the two can't drift. The real branch mkdirs the parent and passes output_path to combine_mooring_pdf.
• Added the --pdf-dir DIR argument to the report subparser. It only affects PDF placement; building the PDF still needs --pdf or --all. run does not build PDFs, so it is untouched.
• Tests: resolve_pdf_path (default beside-HTML, --pdf-dir override, and a purity check that no directory is created) plus two --pdf-dir CLI-parse cases.

Breaking changes

None. --pdf-dir is opt-in; with it unset, PDF output is byte-for-byte where it was before. The speedup is print-CSS only and does not change output content.

Notes

Follow-up (not in this PR): the raw-opaque provenance blob is ugly in a table regardless of layout — truncate it or wrap it in <details>.

[Copilot]

🟢 Approval recommended

The changes are cohesive, low-risk, and include targeted unit tests covering the new path-resolution behavior and CLI parsing.

Pull request overview

This PR improves PDF reporting in oceanarray by (1) speeding up WeasyPrint PDF rendering via a print-CSS table layout change and (2) adding an opt-in report --pdf-dir DIR flag to centralize combined PDF outputs into a shared directory.

Changes:

• Set print CSS tables to table-layout: fixed (with width: 100%) to avoid pathological intrinsic-width scans during PDF rendering.
• Introduce paths.resolve_pdf_path() and wire it into cmd_report for both dry-run preview and real PDF generation, plus add the --pdf-dir CLI flag.
• Add unit tests for PDF path resolution and CLI parsing of --pdf-dir.

File summaries

File	Description
tests/unit/test_paths.py	Adds unit tests for resolve_pdf_path including default behavior, override behavior, and purity (no mkdir side effects).
tests/unit/test_cli.py	Extends CLI parser tests to cover report --pdf-dir parsing and default None behavior.
oceanarray/reports/_pdf.py	Updates print CSS to use fixed table layout for major WeasyPrint performance gains on wide/large cells.
oceanarray/paths.py	Adds resolve_pdf_path() as a single source of truth for combined PDF output location selection.
oceanarray/cli.py	Adds --pdf-dir to report, uses resolve_pdf_path() in dry-run and real PDF flow, and passes an explicit output_path to the PDF combiner.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 0
• Review effort level: Lite

---

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