What's wrong
The documented way to run the PDF comparison on your own machine does not work. The code snippet given for it imports a module path that no longer exists, so copying it produces an immediate error rather than a report.
docs/web-compare.md line 50:
from compare.pdf import compare_pdfs_html
Run against develop at 97f91ba:
ModuleNotFoundError: No module named 'compare'
The diff engine moved into an installable package in #398 (ship the diff engine as an installable src/deltatrack package, recorded as ADR 0017), which relocated compare/ from the repository root to src/deltatrack/compare/. The working import is:
from deltatrack.compare.pdf import compare_pdfs_html # confirmed working
How it surfaced
Reviewing the documentation on how to run a comparison, and executing the snippets rather than reading them. Both forms above were run in this session.
Version history is consistent with a routine miss rather than anything unusual: src/deltatrack/compare/pdf.py was added on 2026-07-28 by the package move, and docs/web-compare.md was last modified the same day by an unrelated change that moved dev-only modules off the repository root, so the snippet was not revisited when the path it names changed.
Why it matters
That snippet is the documented way to run locally the exact pipeline the public upload page runs. It is what someone would reach for first when investigating a difference between the website's output and their own, and it fails on its first line. The surrounding page is otherwise the map of how the web app relates to the command line, so a reader has no easy signal that the error is stale documentation rather than a broken install.
What to do
Change the import to from deltatrack.compare.pdf import compare_pdfs_html.
Unverified
Only the import line was executed. The rest of that snippet, which reads the two PDF files, calls compare_pdfs_html with the label arguments, and writes the output, was not run, so it may carry further drift from the same package move. Worth executing the whole block when fixing the import rather than assuming the remainder still matches the current signature.
Refs #398
What's wrong
The documented way to run the PDF comparison on your own machine does not work. The code snippet given for it imports a module path that no longer exists, so copying it produces an immediate error rather than a report.
docs/web-compare.mdline 50:Run against
developat97f91ba:The diff engine moved into an installable package in #398 (ship the diff engine as an installable
src/deltatrackpackage, recorded as ADR 0017), which relocatedcompare/from the repository root tosrc/deltatrack/compare/. The working import is:How it surfaced
Reviewing the documentation on how to run a comparison, and executing the snippets rather than reading them. Both forms above were run in this session.
Version history is consistent with a routine miss rather than anything unusual:
src/deltatrack/compare/pdf.pywas added on 2026-07-28 by the package move, anddocs/web-compare.mdwas last modified the same day by an unrelated change that moved dev-only modules off the repository root, so the snippet was not revisited when the path it names changed.Why it matters
That snippet is the documented way to run locally the exact pipeline the public upload page runs. It is what someone would reach for first when investigating a difference between the website's output and their own, and it fails on its first line. The surrounding page is otherwise the map of how the web app relates to the command line, so a reader has no easy signal that the error is stale documentation rather than a broken install.
What to do
Change the import to
from deltatrack.compare.pdf import compare_pdfs_html.Unverified
Only the import line was executed. The rest of that snippet, which reads the two PDF files, calls
compare_pdfs_htmlwith the label arguments, and writes the output, was not run, so it may carry further drift from the same package move. Worth executing the whole block when fixing the import rather than assuming the remainder still matches the current signature.Refs #398