plan: review pdf-generation method fitness for quicknxsv2 docs

# Review pdf-generation method fitness-for-purpose for quicknxsv2 docs

**Status**: open — pre-emptive review for documentation/reporting needs

that may arise during the modularization effort.

## Note on this branch's current state

**There is no `pdf-tools/` directory on this branch as of the time

this plan was written.** The original instruction to file this plan

came alongside the same plan being filed on `genesis-proposal-work`

(which *does* have `pdf-tools/`). The framing here therefore is

forward-looking: *if* this branch eventually needs to generate PDF

output (architecture docs, refactoring rationale, reduction-pipeline

diagrams for stakeholders), what tool should be used, and is the

inherited `pdf-tools/md2pdf.py` from sister branches the right

choice?

If the next session opens this branch and finds a `pdf-tools/`

directory has been added in the meantime, treat that as the artefact

to evaluate. Otherwise, evaluate hypothetically against the needs of

this branch.

## Why this needs reviewing

The `pdf-tools/md2pdf.py` script that lives in sister branches

(`instrument-motion-investigations`, `genesis-proposal-work`, the

superseded `bl4a-*` and `bl4b-tthd-investigation`) was originally

built for **short technical investigation reports** (DANGLE, S3-Gap,

tthd, hs-HLS): ~30 KB Markdown → ~110 KB / ~15-page PDF, with a

title page, TOC, and an opinionated amber executive-summary callout.

quicknxsv2 documentation needs are different and not yet enumerated.

Plausible needs include:

- **Architecture / refactoring rationale documents** for stakeholders

  (instrument scientists, software-team leads) — somewhat similar

  to investigation reports in length and audience, but with code

  diagrams that need clean rendering.

- **Module-level reference docs** generated from docstrings —

  warrants a different toolchain entirely (Sphinx, MkDocs, pdoc,

  pydoc-markdown).

- **User-facing reduction-workflow walkthroughs** with screenshots,

  parameter tables, scientific notation in formulas — needs proper

  figure handling and equation rendering.

- **Conference posters / presentation slides** — would not use a

  PDF-from-Markdown pipeline at all.

Without enumerating the actual needs first, defaulting to "copy

`pdf-tools/` from a sister branch" risks landing on a tool that's

opinionated for the wrong use case.

## What "review" means here

Scoped as **review and recommend**, not "build the tooling now."

Deliverable: a written recommendation the user can act on.

### Evaluation steps

1. **Inventory the actual documentation needs** for this branch's

   modularization work. Read the quicknxsv2 source structure plus

   any existing docs/ or doc/ directory.

   - What artefacts will the modularization effort produce?

   - Who is each artefact's audience (scientists / developers /

     project leads)?

   - What output format does the audience actually consume

     (PDF / HTML / Wiki / Confluence / Word)?

2. **If PDF turns out to be needed**, evaluate the existing

   `pdf-tools/md2pdf.py` (from the sister branch

   `instrument-motion-investigations`) against the inventoried needs:

   - Is "Markdown → opinionated PDF" the right shape, or is

     something more flexible needed (figures, equations, code

     blocks with syntax highlighting, cross-references)?

   - Maintenance: who owns the template if the rendering needs

     evolve?

3. **Survey alternatives** appropriate for software-architecture

   documentation:

   - **Sphinx + LaTeX/PDF** — standard for Python projects with

     code references and module index

   - **MkDocs / mkdocs-material** — modern HTML-first, but PDF

     export plugins exist

   - **Quarto** — strong for technical documents that mix narrative,

     code, figures

   - **pdoc / pydoc-markdown** — auto-generated API docs from

     docstrings; pairs well with hand-written narrative

   - **Pandoc + LaTeX template** — same general capability as

     Quarto, more LaTeX-native

4. **Decision matrix** weighting:

   - Fit to audience (scientists vs developers)

   - Auto-generation capability (do we want

     module-index-from-docstrings, or only hand-written narrative?)

   - Output flexibility (PDF / HTML / both)

   - Maintenance burden across the modularization timeline

   - Ecosystem fit for a Python+Qt scientific package

5. **Recommend** one of:

   - No tool needed (HTML wiki / Confluence is enough)

   - Adopt `pdf-tools/md2pdf.py` from the sister branch as-is, with

     known limitations documented

   - Adopt one of the surveyed alternatives, with a one-pager

     migration plan

   - Hybrid (e.g., Sphinx for API reference + md2pdf for hand-written

     narrative reports)

## Related context

- Sister branch `genesis-proposal-work` has the same plan deferred

  for a different use case (US Government proposal documents); the

  evaluation logic carries over but the conclusions will likely

  differ since the audiences and templates are unrelated.

- Sister branch `instrument-motion-investigations` is where

  `pdf-tools/` originated and where it's *known* fit-for-purpose;

  reading its CLAUDE.md "Investigation-report PDF workflow" section

  shows the intended use case as a baseline.

- The user's preference (per `~/.claude/CLAUDE.md` `[ALWAYS] Design

  framing` section) is **robust over simplest**. Defaulting to "copy

  pdf-tools from the sister branch because it works there" is the

  simple option; doing the inventory and matching tool to need is

  the robust one.

## Suggested next session

1. Skim this file and the related plan on `genesis-proposal-work`.

2. Spend 30 minutes with the quicknxsv2 repo structure to inventory

   what documentation artefacts the modularization will produce and

   who consumes them.

3. If PDF need is real, run a representative test against

   `pdf-tools/md2pdf.py` (cherry-pick or copy from a sister branch

   for the test) and against one or two alternatives.

4. Write the decision-matrix recommendation back into this file (or

   a sibling `pdf-tools-fitness-recommendation.md`).

5. Bring the recommendation to the user before doing any tool adoption.