calkit-python 0.47.7__tar.gz → 0.47.8__tar.gz

{calkit_python-0.47.7 → calkit_python-0.47.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: calkit-python
-Version: 0.47.7
+Version: 0.47.8
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues

{calkit_python-0.47.7 → calkit_python-0.47.8}/calkit/cli/latex.py

@@ -345,6 +345,9 @@ _VERBATIM_PARAM_RE = re.compile(
     r"(\\(?:verbatiminput\*?|lstinputlisting))"
     r"(?=\s*(?:\[[^\]\n]*\])?\s*\{[^}\n]*#[0-9])"
 )
+_INPUT_WRAPPER_RE = re.compile(
+    r"\\([A-Za-z@]+)\*?\s*(?:\[[^\]]*\]\s*)*\{\s*\\(?:input|include)\s*\{"
+)
 get_diff_path = calkit.latex.get_diff_path
 _default_base_ref = calkit.latex.default_base_ref
 
@@ -409,7 +412,9 @@ def diff(
         typer.Option(
             "--latexmk-rc",
             "-r",
-            help="Path to a latexmkrc file to build the marked-up document with.",
+            help=(
+                "Path to a latexmkrc file to build the marked-up document with."
+            ),
         ),
     ] = None,
     latexmk_args: Annotated[
@@ -473,7 +478,11 @@ def diff(
         bool,
         typer.Option(
             "--keep-tex",
-            help="Keep the generated diff .tex file for inspection.",
+            help=(
+                "Keep the old, new, and diff .tex files beside the diff "
+                "PDF for inspection, e.g., "
+                ".calkit/latex-diffs/v1/paper/main-old.tex."
+            ),
         ),
     ] = False,
     no_check: Annotated[
@@ -508,6 +517,53 @@ def diff(
     the comparison shows its own.
     """
 
+    def stage_path(stage: dict, path: str) -> str:
+        """A stage's path in the project's frame rather than its wdir's."""
+        return Path(
+            os.path.normpath(os.path.join(stage.get("wdir") or "", path))
+        ).as_posix()
+
+    def find_latex_stage() -> tuple[str | None, dict | None]:
+        """The pipeline stage that builds the document, if any."""
+        ck_info = calkit.load_calkit_info()
+        stages = (ck_info.get("pipeline") or {}).get("stages") or {}
+        target = Path(os.path.normpath(tex_file)).as_posix()
+        for name, stage in stages.items():
+            if (
+                isinstance(stage, dict)
+                and stage.get("kind") == "latex"
+                and stage_path(stage, stage.get("target_path") or "") == target
+            ):
+                return name, stage
+        return None, None
+
+    def stage_inputs(name: str, stage: dict) -> list[str]:
+        """What a stage's diffs fetch at each revision.
+
+        Its dependencies in the compiled pipeline, which include other
+        stages' outputs it reads, found there since calkit.yaml only names
+        the stages they come from.
+        """
+        from calkit.models.pipeline import LatexStage
+
+        try:
+            dvc_stage = calkit.ryaml.load(Path("dvc.yaml").read_text())[
+                "stages"
+            ][name]
+            deps = [
+                dep if isinstance(dep, str) else next(iter(dep))
+                for dep in dvc_stage.get("deps") or []
+            ]
+        except Exception:
+            deps = LatexStage.model_validate(stage | {"name": name}).dvc_deps
+        skip = {tex_file, latexmk_rc_path}
+        return [
+            path
+            for dep in deps
+            if (path := stage_path(stage, dep)) not in skip
+            and not path.startswith(".calkit/")
+        ]
+
     def fetch_dvc_inputs(root: str, rev: str, paths: list[str]) -> list[str]:
         """Fetch the DVC-tracked content of ``paths`` at ``rev`` into ``root``.
 
@@ -629,7 +685,9 @@ def diff(
         Detection finds a file by its own name or pointer, but a file in a
         directory DVC tracks as a whole has only the directory's pointer,
         which can't say what's inside, so those directories beside the
-        document are included whole.
+        document are included whole. Neither finds another stage's output
+        DVC doesn't cache, so the pipeline's inputs for the document are
+        added too.
         """
         doc_dir = Path(root, os.path.dirname(tex_file))
         pointed = [
@@ -637,7 +695,8 @@ def diff(
             for p in sorted(doc_dir.rglob("*.dvc"))
             if p.is_file()
         ]
-        return calkit.latex.detect_inputs(tex_file, wdir=root) + pointed
+        detected = calkit.latex.detect_inputs(tex_file, wdir=root)
+        return detected + pointed + pipeline_inputs
 
     def point_changed_figures_at_base(base_root: str, head_root: str) -> None:
         """Make the older side's changed figures refer to its own copies.
@@ -698,6 +757,20 @@ def diff(
         from_ref = _default_base_ref(repo)
     if to_ref is None and not os.path.isfile(tex_file):
         raise_error(f"{tex_file} does not exist")
+    # A document the pipeline builds is diffed the way it's built, with its
+    # stage's environment, settings, and inputs, unless told otherwise
+    stage_name, stage = find_latex_stage()
+    pipeline_inputs: list[str] = []
+    if stage is not None:
+        if environment is None:
+            environment = stage.get("environment")
+        if latexmk_rc_path is None and stage.get("latexmkrc_path"):
+            latexmk_rc_path = stage_path(stage, stage["latexmkrc_path"])
+        latexmk_args = latexmk_args or list(stage.get("latexmk_args") or [])
+        latexdiff_args = latexdiff_args or list(
+            stage.get("latexdiff_args") or []
+        )
+        pipeline_inputs = stage_inputs(str(stage_name), stage)
     if output is None:
         output = get_diff_path(
             tex_file,
@@ -766,9 +839,9 @@ def diff(
             break_verbatim_params(root)
         point_changed_figures_at_base(checkouts["base"], head_root)
         _build_diff(
-            base_tex=sides["base"],
-            head_tex=sides["head"],
-            tex_file=tex_file,
+            base_tex_fpath=sides["base"],
+            head_tex_fpath=sides["head"],
+            tex_file_fpath=tex_file,
             head_root=head_root,
             output=output,
             environment=environment,
@@ -825,9 +898,9 @@ def _remove_worktree(path: str) -> None:
 
 
 def _build_diff(
-    base_tex: str,
-    head_tex: str,
-    tex_file: str,
+    base_tex_fpath: str,
+    head_tex_fpath: str,
+    tex_file_fpath: str,
     head_root: str,
     output: str,
     environment: str | None,
@@ -840,39 +913,63 @@ def _build_diff(
     force: bool,
     verbose: bool,
 ) -> None:
-    """Mark up one document against another and build the result."""
+    """Mark up one document against another and build the result.
+
+    base_tex_fpath is the older revision's document, head_tex_fpath the
+    newer revision's, and tex_file_fpath the document as named on the
+    command line. head_root is where the newer side lives: a checkout,
+    or the working tree, beside which the marked-up document is built
+    so its relative inputs resolve.
+    """
     # Built beside the newer side, so \graphicspath, \bibliography, and
     # relative \includegraphics resolve the way they do for the real thing,
     # against that revision's own files
-    tex_dir = os.path.dirname(tex_file) or "."
+    tex_dir = os.path.dirname(tex_file_fpath) or "."
     build_dir = os.path.normpath(os.path.join(head_root, tex_dir))
-    stem = Path(tex_file).stem
-    diff_tex = os.path.join(build_dir, f"{stem}-diff.tex")
-    # Where --keep-tex leaves it: beside the document, since a checkout is
-    # removed afterwards
-    kept_tex = os.path.normpath(os.path.join(tex_dir, f"{stem}-diff.tex"))
+    stem = Path(tex_file_fpath).stem
+    diff_tex_fpath = os.path.join(build_dir, f"{stem}-diff.tex")
+    # Where --keep-tex leaves its copies: beside the diff PDF, since a
+    # checkout is removed afterwards. The old and new files are what
+    # latexdiff saw, after verbatim fixes and figure repointing, so a
+    # --flatten or macro expansion failure can be inspected.
+    kept_stem = os.path.splitext(output)[0]
+    kept_diff_fpath = f"{kept_stem}-diff.tex"
+    kept_old_fpath = f"{kept_stem}-old.tex"
+    kept_new_fpath = f"{kept_stem}-new.tex"
+    marked_up: bytes | None = None
     aux_dir = os.path.join(build_dir, calkit.latex.DIFF_AUX_DIRNAME)
     try:
         # --flatten pulls \input and \include files into one document on
         # each side, so a multi-file paper compares as a whole
         latexdiff_cmd = ["latexdiff", "--flatten", "--encoding=utf8"]
-        # A checkout's verbatim inputs named by macro parameters are already
-        # broken, so this only finds the working tree's, which can't be
-        # edited. A filter breaks those instead, though latexdiff's
-        # --filter-script mangles anything outside Latin-1.
-        sources = [base_tex, head_tex] + [
+        sources = [base_tex_fpath, head_tex_fpath] + [
             path
-            for side in (base_tex, head_tex)
+            for side in (base_tex_fpath, head_tex_fpath)
             for path in calkit.latex.detect_inputs(side)
             if Path(path).suffix in calkit.latex._SOURCE_EXTS
         ]
-        if any(
-            os.path.isfile(path)
-            and _VERBATIM_PARAM_RE.search(
-                Path(path).read_text(encoding="utf-8", errors="replace")
-            )
+        texts = [
+            Path(path).read_text(encoding="utf-8", errors="replace")
             for path in sources
-        ):
+            if os.path.isfile(path)
+        ]
+        # A macro wrapping an \input or \include, e.g., one making an
+        # appendix single column, gets the whole flattened file as its
+        # argument, which latexdiff would otherwise mark up as one token
+        wrappers = sorted(
+            {
+                name
+                for text in texts
+                for name in _INPUT_WRAPPER_RE.findall(text)
+            }
+        )
+        if wrappers:
+            latexdiff_cmd.append("--append-textcmd=" + ";".join(wrappers))
+        # A checkout's verbatim inputs named by macro parameters are already
+        # broken, so this only finds the working tree's, which can't be
+        # edited. A filter breaks those instead, though latexdiff's
+        # --filter-script mangles anything outside Latin-1.
+        if any(_VERBATIM_PARAM_RE.search(text) for text in texts):
             filter_path = Path(DIFF_TMP_DIR, "verbatim-param-filter.pl")
             os.makedirs(filter_path.parent, exist_ok=True)
             # latexdiff appends a newline to what it sends, so drop it
@@ -896,7 +993,7 @@ def _build_diff(
         # defaults
         latexdiff_cmd += latexdiff_args
         cmd = _tex_cmd(
-            latexdiff_cmd + [base_tex, head_tex],
+            latexdiff_cmd + [base_tex_fpath, head_tex_fpath],
             environment=environment,
             no_check=no_check,
             verbose=verbose,
@@ -904,7 +1001,9 @@ def _build_diff(
         )
         typer.echo("Marking up the document with latexdiff")
         try:
-            marked_up = subprocess.check_output(cmd)
+            # No stdin, so an environment's container isn't given a TTY,
+            # which would merge latexdiff's warnings into the document
+            marked_up = subprocess.check_output(cmd, stdin=subprocess.DEVNULL)
         except FileNotFoundError:
             raise_error(
                 "latexdiff was not found; it ships with TeX Live, so a "
@@ -944,8 +1043,7 @@ def _build_diff(
         ):
             typer.echo(f"{output} is up to date")
             return
-        with open(diff_tex, "wb") as f:
-            f.write(marked_up)
+        Path(diff_tex_fpath).write_bytes(marked_up)
         os.makedirs(aux_dir, exist_ok=True)
         rel_aux = calkit.latex.DIFF_AUX_DIRNAME
         latexmk_cmd = ["latexmk"]
@@ -965,7 +1063,7 @@ def _build_diff(
         # User pass-through args come last so they can override Calkit's
         # defaults
         latexmk_cmd += latexmk_args
-        latexmk_cmd.append(diff_tex)
+        latexmk_cmd.append(diff_tex_fpath)
         cmd = _tex_cmd(
             latexmk_cmd,
             environment=environment,
@@ -993,10 +1091,13 @@ def _build_diff(
             if excerpt:
                 typer.echo(f"From {log_path.as_posix()}:", err=True)
                 typer.echo("\n".join(excerpt), err=True)
-            raise_error(
-                "latexmk failed on the marked-up document with exit status "
-                f"{e.returncode}; rerun with --keep-tex to inspect it"
+            msg = (
+                "latexmk failed on the diff document with exit code "
+                f"{e.returncode}"
             )
+            if not keep_tex:
+                msg += "; rerun with --keep-tex to inspect"
+            raise_error(msg)
         built = os.path.join(aux_dir, f"{stem}-diff.pdf")
         if not os.path.isfile(built):
             raise_error("latexmk did not produce a PDF")
@@ -1007,16 +1108,28 @@ def _build_diff(
         if os.path.abspath(head_root) == os.path.abspath("."):
             shutil.rmtree(aux_dir, ignore_errors=True)
         os.makedirs(os.path.dirname(state_path), exist_ok=True)
-        with open(state_path, "w") as f:
-            f.write(digest)
+        Path(state_path).write_text(digest)
         typer.echo(f"Wrote {output}")
     finally:
-        if os.path.isfile(diff_tex):
-            in_place = os.path.abspath(diff_tex) == os.path.abspath(kept_tex)
-            if keep_tex and not in_place:
-                shutil.copy(diff_tex, kept_tex)
-            if not keep_tex or not in_place:
-                os.remove(diff_tex)
+        if keep_tex:
+            os.makedirs(os.path.dirname(output) or ".", exist_ok=True)
+            if marked_up is not None:
+                Path(kept_diff_fpath).write_bytes(marked_up)
+            for src, kept_fpath in (
+                (base_tex_fpath, kept_old_fpath),
+                (head_tex_fpath, kept_new_fpath),
+            ):
+                if os.path.isfile(src):
+                    shutil.copy(src, kept_fpath)
+            for kept_fpath in (
+                kept_old_fpath,
+                kept_new_fpath,
+                kept_diff_fpath,
+            ):
+                if os.path.isfile(kept_fpath):
+                    typer.echo(f"Kept {kept_fpath} for inspection")
+        if os.path.isfile(diff_tex_fpath):
+            os.remove(diff_tex_fpath)
 
 
 @latex_app.command(name="to-docx")

{calkit_python-0.47.7 → calkit_python-0.47.8}/calkit/models/pipeline.py

@@ -989,11 +989,16 @@ class LatexStage(Stage):
         default=[],
         description="Comparisons to keep for this document, each a pair of "
         "revisions. A bare string is shorthand for comparing that revision "
-        "against the working tree.",
+        "against HEAD.",
     )
     diff_pdf_storage: Literal["git", "dvc"] | None = Field(
         default="dvc", description="Where to store the resulting diff PDFs."
     )
+    keep_diff_tex: bool = Field(
+        default=False,
+        description="Keep the old, new, and marked-up .tex files beside "
+        "each diff PDF for inspection.",
+    )
     verbose: bool = Field(
         default=False, description="Show full latexmk output."
     )
@@ -1081,6 +1086,8 @@ class LatexStage(Stage):
                 cmd += f" --latexmk-arg {shlex.quote(arg)}"
             for arg in self.latexdiff_args:
                 cmd += f" --latexdiff-arg {shlex.quote(arg)}"
+            if self.keep_diff_tex:
+                cmd += " --keep-tex"
             # Each revision gets its own copies of any of these that are
             # tracked with DVC, since a checkout only has their pointers
             for input_path in inputs:

{calkit_python-0.47.7 → calkit_python-0.47.8}/calkit/pipeline.py

@@ -2,6 +2,7 @@
 
 import itertools
 import os
+import posixpath
 import re
 import warnings
 from collections.abc import Callable
@@ -1407,11 +1408,16 @@ def _ensure_latex_aux_gitignore(
     can be wiped by a clean build (``latexmk -C``). The globs are unanchored,
     so aux files are caught wherever latexmk writes them relative to the
     source -- next to it, or in an ``aux``/output subdirectory via
-    ``$aux_dir``/``$out_dir``/``output_dir``. ``*.pdf`` is never ignored so the
-    compiled output stays tracked.
+    ``$aux_dir``/``$out_dir``/``output_dir``. A stage's own ``aux_dir`` is
+    also ignored whole. ``*.pdf`` is never ignored so the compiled output
+    stays tracked.
 
     Returns True if ``.gitignore`` was modified.
     """
+
+    def norm(path: str) -> str:
+        return posixpath.normpath(path.replace("\\", "/"))
+
     aux_globs = [
         "*.aux",
         "*.bbl",
@@ -1434,6 +1440,25 @@ def _ensure_latex_aux_gitignore(
     base = os.path.join(wdir or ".", stage.wdir) if stage.wdir else wdir or "."
     source_dir = os.path.dirname(stage.target_path)
     gitignore_path = os.path.join(base, source_dir, ".gitignore")
+    # An aux dir is ignored whole, since packages like glossaries write
+    # files with extensions no list could anticipate. One outside the
+    # source directory can't be named from its .gitignore. Pure path
+    # arithmetic, since os.path.relpath resolves 'aux' to a device on
+    # Windows.
+    if stage.aux_dir is not None:
+        aux = norm(stage.aux_dir)
+        src = norm(source_dir or ".")
+        if src == ".":
+            inside = aux != "." and not aux.startswith(("../", "/"))
+            rel = aux
+        else:
+            inside = aux.startswith(src + "/")
+            rel = aux[len(src) + 1 :]
+        if inside:
+            aux_globs.append(f"/{rel}/*")
+            # Unless the PDF goes there too
+            if stage.output_dir is not None and norm(stage.output_dir) == aux:
+                aux_globs.append(f"!/{rel}/*.pdf")
     return _write_managed_gitignore_block(
         gitignore_path, marker="calkit latex aux files", lines=aux_globs
     )

{calkit_python-0.47.7 → calkit_python-0.47.8}/calkit/tests/cli/test_latex.py

@@ -390,7 +390,8 @@ def test_latex_diff_dvc_inputs(tmp_dir, tmp_path_factory):
         f.write("\\documentclass{article}\n")
         f.write("\\newcommand{\\wc}[1]{\\verbatiminput{#1.wcsum}}\n")
         f.write("\\begin{document}\nGreen\u2019s function\n")
-        f.write("\\includegraphics{figs/plot}\n\\end{document}\n")
+        f.write("\\includegraphics{figs/plot}\n")
+        f.write("\\singlecol{\\input{setup}}\n\\end{document}\n")
     with open("paper/.latexmkrc", "w") as f:
         f.write("$aux_dir = 'aux';\n")
     with open("paper/figs/plot.png", "w") as f:
@@ -451,7 +452,11 @@ def test_latex_diff_dvc_inputs(tmp_dir, tmp_path_factory):
     output = get_diff_path("paper/main.tex", "v1", "HEAD")
     with open(output) as f:
         assert f.read() == "old\nnew\n"
-    with open("paper/main-diff.tex", encoding="utf-8") as f:
+    # --keep-tex keeps what latexdiff saw beside the diff PDF, so a
+    # --flatten or macro expansion failure can be inspected
+    kept_stem = output.removesuffix(".pdf")
+    assert not os.path.exists("paper/main-diff.tex")
+    with open(f"{kept_stem}-diff.tex", encoding="utf-8") as f:
         marked_up = f.read()
     # A verbatim input named by a macro parameter is broken onto its own
     # line in each checkout rather than by latexdiff's --filter-script,
@@ -459,10 +464,21 @@ def test_latex_diff_dvc_inputs(tmp_dir, tmp_path_factory):
     assert "\\verbatiminput%\n{#1.wcsum}" in marked_up
     assert "Green\u2019s function" in marked_up
     with open(stubs / "latexdiff-args.txt") as f:
-        assert "--filter-script" not in f.read()
+        latexdiff_args = f.read()
+    assert "--filter-script" not in latexdiff_args
+    # A macro wrapping an input is marked up as text, not one token
+    assert "--append-textcmd=singlecol" in latexdiff_args
     assert "\\includegraphics{../../base/paper/figs/plot.png}" in marked_up
     assert "\\includegraphics{figs/plot}" in marked_up
     assert not os.path.exists("paper/figs")
+    with open(f"{kept_stem}-old.tex", encoding="utf-8") as f:
+        old_tex = f.read()
+    with open(f"{kept_stem}-new.tex", encoding="utf-8") as f:
+        new_tex = f.read()
+    assert "\\verbatiminput%\n{#1.wcsum}" in old_tex
+    assert "\\verbatiminput%\n{#1.wcsum}" in new_tex
+    assert "../../base/paper/figs/plot.png" in old_tex
+    assert "../../base/paper/figs/plot.png" not in new_tex
     # The diff is built with the document's rc file, read before the
     # directories Calkit sets so those win, and latexdiff gets its options
     with open(stubs / "latexmk-args.txt") as f:
@@ -548,7 +564,43 @@ def test_latex_diff_dvc_inputs(tmp_dir, tmp_path_factory):
     assert result.returncode != 0
     assert "! Undefined control sequence." in result.stderr
     assert "l.3 \\oops" in result.stderr
-    assert "exit status 12" in result.stderr
+    assert "exit code 12" in result.stderr
+    # Detection can't find another stage's uncached output at a revision
+    os.remove(stubs / "setup.txt")
+    bare = ["calkit", "latex", "diff", "paper/main.tex", "--from", "v1"]
+    bare += ["--to", "HEAD", "--force"]
+    result = subprocess.run(bare, capture_output=True, text=True, env=env)
+    assert result.returncode == 0, result.stderr
+    assert not os.path.exists(stubs / "setup.txt")
+    # But a document the pipeline builds is diffed the way its stage builds
+    # it, fetching what the compiled stage depends on
+    with open("calkit.yaml", "w") as f:
+        f.write(
+            "pipeline:\n"
+            "  stages:\n"
+            "    paper:\n"
+            "      kind: latex\n"
+            "      target_path: paper/main.tex\n"
+            "      latexmkrc_path: paper/.latexmkrc\n"
+            "      latexdiff_args: [--type=CFONT]\n"
+        )
+    with open("dvc.yaml", "a") as f:
+        f.write(
+            "  paper:\n"
+            "    cmd: calkit latex build paper/main.tex\n"
+            "    deps: [paper/main.tex, paper/.latexmkrc, paper/setup.tex]\n"
+        )
+    result = subprocess.run(bare, capture_output=True, text=True, env=env)
+    assert result.returncode == 0, result.stderr
+    with open(stubs / "setup.txt") as f:
+        assert f.read() == "present\n"
+    with open(stubs / "latexdiff-args.txt") as f:
+        assert "--type=CFONT" in f.read().split()
+    with open(stubs / "latexmk-args.txt") as f:
+        latexmk_args = f.read().split()
+    assert latexmk_args[latexmk_args.index("-r") + 1].endswith(
+        "paper/.latexmkrc"
+    )
 
 
 def test_marked_up_digest_ignores_the_header():

{calkit_python-0.47.7 → calkit_python-0.47.8}/calkit/tests/models/test_pipeline.py

@@ -630,11 +630,12 @@ def test_latex_stage_diffs():
         latexdiff_args=["--graphics-markup=both"],
         inputs=["pubs/paper-1/figs/"],
         diffs=[["v1", "v2"]],
+        keep_diff_tex=True,
     )
     assert configured.extra_dvc_stages()["paper-1-diff-v1-v2"]["cmd"] == (
         "calkit latex diff -e tex --no-check --from v1 --to v2 "
         "-r pubs/paper-1/.latexmkrc --latexmk-arg -shell-escape "
-        "--latexdiff-arg --graphics-markup=both "
+        "--latexdiff-arg --graphics-markup=both --keep-tex "
         "--input pubs/paper-1/figs/ "
         "--output-dir .calkit/latex-diffs/v1..v2 pubs/paper-1/main.tex"
     )

{calkit_python-0.47.7 → calkit_python-0.47.8}/calkit/tests/test_pipeline.py

@@ -2647,6 +2647,33 @@ def test_ensure_latex_aux_gitignore(tmp_dir):
     # The block is not duplicated and the unrelated entry survives
     assert contents.count("# >>> calkit latex aux files") == 1
     assert "figs/*.png" in contents
+    # An aux dir is ignored whole, since packages write files with any
+    # extension, but not one outside the source directory
+    stage.output_dir = None
+    stage.aux_dir = "paper/aux"
+    assert _ensure_latex_aux_gitignore(stage)
+    with open(gitignore_path) as f:
+        contents = f.read()
+    assert "/aux/*\n" in contents
+    assert "!/aux/*.pdf" not in contents
+    # Unless the PDF goes there too
+    stage.output_dir = "paper/aux"
+    assert _ensure_latex_aux_gitignore(stage)
+    with open(gitignore_path) as f:
+        assert "!/aux/*.pdf" in f.read()
+    stage.output_dir = None
+    stage.aux_dir = "build/aux"
+    assert _ensure_latex_aux_gitignore(stage)
+    with open(gitignore_path) as f:
+        assert "aux/*" not in f.read()
+    # Nor the source directory itself
+    stage.aux_dir = "paper"
+    assert _ensure_latex_aux_gitignore(stage) is False
+    # Windows separators name the same directory
+    stage.aux_dir = "paper\\aux"
+    assert _ensure_latex_aux_gitignore(stage)
+    with open(gitignore_path) as f:
+        assert "/aux/*\n" in f.read()
     # When the stage has a wdir, paths are relative to it, so the .gitignore
     # lands under <wdir>/<source dir>, not the project root
     os.makedirs("sub/doc")

{calkit_python-0.47.7 → calkit_python-0.47.8}/docs/cli-reference.md

@@ -3425,7 +3425,7 @@ Options:
 | `--latexdiff-arg`    | str     | no       |         | Extra argument to pass through to latexdiff, e.g., '--type=CFONT'. Changed figures are shown old and new by default; pass '--graphics-markup=new-only' to show only the new. Repeat the option to pass more than one. |
 | `--input`            | str     | no       |         | File or directory the document reads. Anything in it tracked with DVC is fetched as it was at each revision. Defaults to the inputs detected in the document. Repeat the option to pass more than one.                |
 | `--force`, `-f`      | boolean | no       | False   | Rebuild even if nothing the diff depends on has changed since it was last built.                                                                                                                                      |
-| `--keep-tex`         | boolean | no       | False   | Keep the generated diff .tex file for inspection.                                                                                                                                                                     |
+| `--keep-tex`         | boolean | no       | False   | Keep the old, new, and diff .tex files beside the diff PDF for inspection, e.g., .calkit/latex-diffs/v1/paper/main-old.tex.                                                                                           |
 | `--no-check`         | boolean | no       | False   | Don't check the environment is valid before running.                                                                                                                                                                  |
 | `--verbose`, `-v`    | boolean | no       | False   | Print verbose output.                                                                                                                                                                                                 |
 

{calkit_python-0.47.7 → calkit_python-0.47.8}/docs/latex.md

@@ -219,22 +219,35 @@ To run all of a document's comparisons:
 calkit run paper-1.diffs
 ```
 
-### Comparing against uncommitted work
+### Comparing on demand
 
-`calkit latex diff` runs a comparison on demand, and with no `--to` the
-newer side is the working tree:
+Diffs created by the pipeline are for memorializing
+committed versions.
+To see uncommitted changes, `calkit latex diff` runs a comparison on demand,
+and with no `--to` option specified, the comparison is the working copy:
 
 ```sh
-calkit latex diff pubs/paper-1/main.tex --from main --env tex
+calkit latex diff pubs/paper-1/main.tex --from main
 # .calkit/local/latex-diffs/main..working/pubs/paper-1/main.pdf
 ```
 
 Those diffs can't be reproduced from two revisions, so they're not tracked,
 ending up in the project's `.calkit/local` directory.
-With no `--from` it compares against the merge base with the default branch.
-DVC-tracked files the document names directly are fetched for the older
-side, but a pipeline output without a `.dvc` file isn't found that way, so
-name any of those with `--input`, e.g., `--input pubs/paper-1/figs/`.
+With no `--from` it compares against the merge base with the default
+branch--typically `main`.
+If a `latex` pipeline stage builds the document,
+the diff is built with the stage configuration, i.e.,
+its environment, settings, and inputs,
+so the diff uses both revisions of the figures, tables, and results.
+
+To see the .tex files sent into `latexdiff`, e.g., when the
+marked-up document fails to build, pass `--keep-tex`,
+or set `keep_diff_tex: true` on the stage.
+The old, new, and marked-up `.tex` files are kept beside the diff PDF,
+e.g., `main-old.tex`, `main-new.tex`, and `main-diff.tex`.
+
+In VS Code, the Calkit extension's "Diff LaTeX Document Against..." command
+does the same from the editor, and opens the result.
 
 ## Interoperability with Microsoft Word
 

{calkit_python-0.47.7 → calkit_python-0.47.8}/docs/pipeline/index.md

@@ -426,8 +426,9 @@ Model class: `LatexStage`
 | `aux_dir`               | str \| None                   | no       | null    | Directory for latexmk auxiliary files.                                                                                                                                        |
 | `latexmkrc_path`        | str \| None                   | no       | null    | Path to a latexmkrc file to use.                                                                                                                                              |
 | `pdf_storage`           | Literal['git', 'dvc'] \| None | no       | 'dvc'   | Where to store the resulting PDF.                                                                                                                                             |
-| `diffs`                 | list[str \| list[str]]        | no       |         | Comparisons to keep for this document, each a pair of revisions. A bare string is shorthand for comparing that revision against the working tree.                             |
+| `diffs`                 | list[str \| list[str]]        | no       |         | Comparisons to keep for this document, each a pair of revisions. A bare string is shorthand for comparing that revision against HEAD.                                         |
 | `diff_pdf_storage`      | Literal['git', 'dvc'] \| None | no       | 'dvc'   | Where to store the resulting diff PDFs.                                                                                                                                       |
+| `keep_diff_tex`         | bool                          | no       | False   | Keep the old, new, and marked-up .tex files beside each diff PDF for inspection.                                                                                              |
 | `verbose`               | bool                          | no       | False   | Show full latexmk output.                                                                                                                                                     |
 | `force`                 | bool                          | no       | False   | Keep compiling despite errors (latexmk -f).                                                                                                                                   |
 | `synctex`               | bool                          | no       | True    | Generate SyncTeX data for editor/PDF navigation.                                                                                                                              |

{calkit_python-0.47.7/vscode-ext → calkit_python-0.47.8/docs}/schemas/calkit.json

@@ -2323,7 +2323,7 @@
         },
         "diffs": {
           "default": [],
-          "description": "Comparisons to keep for this document, each a pair of revisions. A bare string is shorthand for comparing that revision against the working tree.",
+          "description": "Comparisons to keep for this document, each a pair of revisions. A bare string is shorthand for comparing that revision against HEAD.",
           "items": {
             "anyOf": [
               {
@@ -2410,6 +2410,12 @@
           "description": "Arguments over which to run this stage multiple times.",
           "title": "Iterate Over"
         },
+        "keep_diff_tex": {
+          "default": false,
+          "description": "Keep the old, new, and marked-up .tex files beside each diff PDF for inspection.",
+          "title": "Keep Diff Tex",
+          "type": "boolean"
+        },
         "kind": {
           "const": "latex",
           "default": "latex",