Rename build steps to compilation steps.

Author: tobiasraabe

CHANGES.rst

@@ -11,7 +11,7 @@ all releases are available on `Anaconda.org
 ------------------
 
 - :pull:`32` implements a new interface to the compilation process which consists of
-  composable build steps. (Many thanks to :user:`axtimhaus`!:tada:)
+  composable compilation steps. (Many thanks to :user:`axtimhaus`!:tada:)
 
 
 0.1.1 - 2022-02-08

README.rst

@@ -149,66 +149,66 @@ decorator.
 
 .. code-block:: python
 
-    @pytask.mark.latex(build_steps="latexmk")
+    @pytask.mark.latex(compilation_steps="latexmk")
     def task_compile_latex_document():
         ...
 
-The ``@pytask.mark.latex`` decorator has a keyword argument called ``build_steps`` which
-accepts which accepts strings or list of strings pointing to internally implemented
-build steps. Using strings will use the default configuration of this build step. It is
-equivalent to the following.
+The ``@pytask.mark.latex`` decorator has a keyword argument called ``compilation_steps``
+which accepts which accepts strings or list of strings pointing to internally
+implemented compilation steps. Using strings will use the default configuration of this
+compilation step. It is equivalent to the following.
 
 .. code-block::
 
-    from pytask_latex import build_steps
+    from pytask_latex import compilation_steps
 
 
     @pytask.mark.latex(
-        build_steps=build_steps.latexmk(
+        compilation_steps=compilation_steps.latexmk(
             options=("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd")
         )
     )
     def task_compile_latex_document():
         ...
 
-In this example, ``build_steps.latexmk`` is a build step constructor which accepts a set
-of options and creates a build step function.
+In this example, ``compilation_steps.latexmk`` is a compilation step constructor which
+accepts a set of options and creates a compilation step function.
 
 You can pass different options to change the compilation process with latexmk. Here is
 an example for generating a ``.dvi``.
 
 .. code-block:: python
 
     @pytask.mark.latex(
-        build_steps=build_steps.latexmk(
+        compilation_steps=compilation_steps.latexmk(
             options=("--dvi", "--interaction=nonstopmode", "--synctex=1", "--cd")
         )
     )
     def task_compile_latex_document():
         ...
 
-``build_step.latexmk(options)`` generates a build step which is a function with the
-following signature:
+``compilation_step.latexmk(options)`` generates a compilation step which is a function
+with the following signature:
 
 .. code-block::
 
     from pathlib import Path
     import subprocess
 
 
-    def custom_build_step(path_to_tex: Path, path_to_document: Path) -> None:
+    def custom_compilation_step(path_to_tex: Path, path_to_document: Path) -> None:
         ...
         subproces.run(..., check=True)
 
-You can also pass your custom build step with the same signature to the ``build_steps``
-keyword argument of the decorator.
+You can also pass your custom compilation step with the same signature to the
+``compilation_steps`` keyword argument of the decorator.
 
-Each build step receives the path to the LaTeX source file and the path to the final
-document which it uses to call some program on the command line to run another step in
-the compilation process.
+Each compilation step receives the path to the LaTeX source file and the path to the
+final document which it uses to call some program on the command line to run another
+step in the compilation process.
 
-In the future, pytask-latex will provide more build steps for compiling bibliographies,
-glossaries and the like.
+In the future, pytask-latex will provide more compilation steps for compiling
+bibliographies, glossaries and the like.
 
 
 Parametrization
@@ -233,7 +233,7 @@ The following task compiles two latex documents.
 If you want to compile the same document with different command line options, you have
 to include the latex decorator in the parametrization just like with
 ``@pytask.mark.depends_on`` and ``@pytask.mark.produces``. Pass a dictionary for
-possible build steps and their options.
+possible compilation steps and their options.
 
 .. code-block:: python
 
@@ -244,15 +244,15 @@ possible build steps and their options.
             (
                 "document.pdf",
                 {
-                    "build_steps": build_steps.latexmk(
+                    "compilation_steps": compilation_steps.latexmk(
                         ("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd")
                     )
                 },
             ),
             (
                 "document.dvi",
                 {
-                    "build_steps": build_steps.latexmk(
+                    "compilation_steps": compilation_steps.latexmk(
                         ("--dvi", "--interaction=nonstopmode", "--synctex=1", "--cd")
                     )
                 },

src/pytask_latex/build_steps.py

@@ -19,7 +19,7 @@
 from _pytask.nodes import FilePathNode
 from _pytask.nodes import PythonFunctionTask
 from _pytask.parametrize import _copy_func
-from pytask_latex import build_steps as bs
+from pytask_latex import compilation_steps as cs
 from pytask_latex.utils import to_list
 
 
@@ -33,9 +33,9 @@ def task_func():
 
 to
 
-    from pytask_latex import build_steps
+    from pytask_latex import compilation_steps
 
-    @pytask.mark.latex(build_steps.latexmk(options))
+    @pytask.mark.latex(compilation_steps.latexmk(options))
     def task_func():
         ...
 
@@ -45,48 +45,50 @@ def task_func():
 def latex(
     options: str | Iterable[str] | None = None,
     *,
-    build_steps: str | Callable[..., Any] | Sequence[str | Callable[..., Any]] = None,
+    compilation_steps: str
+    | Callable[..., Any]
+    | Sequence[str | Callable[..., Any]] = None,
 ):
     """Specify command line options for latexmk.
 
     Parameters
     ----------
     options
         One or multiple command line options passed to latexmk.
-    build_steps
-        Build steps to compile the document.
+    compilation_steps
+        Compilation steps to compile the document.
 
     """
-    build_steps = ["latexmk"] if build_steps is None else build_steps
+    compilation_steps = ["latexmk"] if compilation_steps is None else compilation_steps
 
     if options is not None:
         warnings.warn(_DEPRECATION_WARNING, DeprecationWarning)
-        out = [bs.latexmk(options)]
+        out = [cs.latexmk(options)]
 
     else:
         out = []
-        for step in to_list(build_steps):
+        for step in to_list(compilation_steps):
             if isinstance(step, str):
-                parsed_step = getattr(bs, step)
+                parsed_step = getattr(cs, step)
                 if parsed_step is None:
-                    raise ValueError(f"Build step {step!r} is unknown.")
+                    raise ValueError(f"Compilation step {step!r} is unknown.")
                 out.append(parsed_step())
             elif callable(step):
                 out.append(step)
             else:
-                raise ValueError(f"Build step {step!r} is not a valid step.")
+                raise ValueError(f"Compilation step {step!r} is not a valid step.")
 
     return out
 
 
-def compile_latex_document(build_steps, path_to_tex, path_to_document):
+def compile_latex_document(compilation_steps, path_to_tex, path_to_document):
     """Replaces the dummy function provided by the user."""
 
-    for step in build_steps:
+    for step in compilation_steps:
         try:
             step(path_to_tex=path_to_tex, path_to_document=path_to_document)
         except CalledProcessError as e:
-            raise RuntimeError(f"Build step {step.__name__} failed.") from e
+            raise RuntimeError(f"Compilation step {step.__name__} failed.") from e
 
 
 @hookimpl
@@ -136,8 +138,10 @@ def pytask_collect_task_teardown(session, task):
 
         merged_mark = _merge_all_markers(task)
         steps = latex(*merged_mark.args, **merged_mark.kwargs)
-        args = get_build_step_args(session, task)
-        task_function = functools.partial(task_function, build_steps=steps, **args)
+        args = get_compilation_step_args(session, task)
+        task_function = functools.partial(
+            task_function, compilation_steps=steps, **args
+        )
 
         task.function = task_function
 
@@ -212,8 +216,8 @@ def _merge_all_markers(task):
     return mark
 
 
-def get_build_step_args(session, task):
-    """Prepare arguments passe to each build step."""
+def get_compilation_step_args(session, task):
+    """Prepare arguments passe to each compilation step."""
     latex_document = _get_node_from_dictionary(
         task.depends_on, session.config["latex_source_key"]
     ).value

src/pytask_latex/collect.py

@@ -0,0 +1,38 @@
+"""This module contains compilation steps for compiling a LaTeX document.
+
+Each compilation step must have the following signature:
+
+.. code-block::
+
+    def compilation_step(path_to_tex: Path, path_to_document: Path):
+        ...
+
+A compilation step constructor must yield a function with this signature.
+
+"""
+from __future__ import annotations
+
+import subprocess
+
+from pytask_latex.path import relative_to
+from pytask_latex.utils import to_list
+
+
+def latexmk(options=("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd")):
+    """Compilation step that calls latexmk."""
+    options = [str(i) for i in to_list(options)]
+
+    def run_latexmk(path_to_tex, path_to_document):
+        job_name_opt = [f"--jobname={path_to_document.stem}"]
+        out_dir_opt = [
+            f"--output-directory={relative_to(path_to_tex, path_to_document.parent)}"
+        ]
+        cmd = (
+            ["latexmk", *options]
+            + job_name_opt
+            + out_dir_opt
+            + [path_to_tex.as_posix()]
+        )
+        subprocess.run(cmd, check=True)
+
+    return run_latexmk

src/pytask_latex/compilation_steps.py

@@ -0,0 +1,36 @@
+"""This module contains functions related to handling paths."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def relative_to(path: Path, relative_to_: Path) -> str:
+    """Create a relative path from one path to another as a string.
+
+    The output folder needs to be declared as a relative path to the directory where
+    the latex source lies.
+
+    1. It must be relative because bibtex / biber, which is necessary for
+       bibliographies, does not accept full paths as a safety measure.
+    2. Due to the ``--cd`` flag, latexmk will change the directory to the one where the
+       source files are. Thus, relative to the latex sources.
+
+    See this `discussion on Github
+    <https://github.com/James-Yu/LaTeX-Workshop/issues/1932#issuecomment-582416434>`_
+    for additional information.
+
+    Example
+    -------
+    >>> import sys
+    >>> from pathlib import Path
+    >>> if sys.platform == "win32":
+    ...     p = Path("C:/Users/user/documents/file.tex")
+    ... else:
+    ...     p = Path("/home/user/documents/file.tex")
+    >>> out = p.parents[2].joinpath("bld", "docs")
+    >>> relative_to(p, out)
+    '../../bld/docs'
+
+    """
+    return Path(os.path.relpath(relative_to_, path.parent)).as_posix()