Implementation of build steps and support for old API (#32)

Co-authored-by: Tobias Raabe <[email protected]>

Author: axtimhaus

CHANGES.rst

@@ -7,96 +7,103 @@ all releases are available on `Anaconda.org
 <https://anaconda.org/conda-forge/pytask-latex>`_.
 
 
+0.1.2 - 2022-xx-xx
+------------------
+
+- :pull:`32` implements a new interface to the compilation process which consists of
+  composable compilation steps. (Many thanks to :user:`axtimhaus`!:tada:)
+
+
 0.1.1 - 2022-02-08
 ------------------
 
-- :gh:`30` skips concurrent CI builds.
-- :gh:`31` deprecates Python 3.6 and add support for Python 3.10.
+- :pull:`30` skips concurrent CI builds.
+- :pull:`31` deprecates Python 3.6 and add support for Python 3.10.
 
 
 0.1.0 - 2021-07-21
 ------------------
 
-- :gh:`23` updates the ``README.rst``.
-- :gh:`24` replaces versioneer with setuptools-scm.
-- :gh:`26` aligns pytask-latex with pytask v0.1.0.
+- :pull:`23` updates the ``README.rst``.
+- :pull:`24` replaces versioneer with setuptools-scm.
+- :pull:`26` aligns pytask-latex with pytask v0.1.0.
 
 
 0.0.12 - 2021-03-05
 -------------------
 
-- :gh:`19` fixes some post-release issues.
-- :gh:`21` adds dependencies to ``setup.py`` and install via ``conda-forge``.
+- :pull:`19` fixes some post-release issues.
+- :pull:`21` adds dependencies to ``setup.py`` and install via ``conda-forge``.
 
 
 0.0.11 - 2021-02-25
 -------------------
 
-- :gh:`18` prepares pytask-latex to be published on PyPI, adds versioneer and more.
+- :pull:`18` prepares pytask-latex to be published on PyPI, adds versioneer and more.
 
 
 0.0.10 - 2021-01-16
 -------------------
 
-- :gh:`16` fixes the scanner by keeping only scanned dependencies which exist. Convert
+- :pull:`16` fixes the scanner by keeping only scanned dependencies which exist. Convert
   args to strings.
 
 
 0.0.9 - 2020-12-28
 ------------------
 
-- :gh:`12` integrates the latex-dependency-scanner to automatically detect dependencies
-  of a LaTeX document and releases v0.0.9.
-- :gh:`13` fixes the CI.
+- :pull:`12` integrates the latex-dependency-scanner to automatically detect
+  dependencies of a LaTeX document and releases v0.0.9.
+- :pull:`13` fixes the CI.
 
 
 0.0.8 - 2020-10-29
 ------------------
 
-- :gh:`11` makes pytask-latex work with pytask v0.0.9.
+- :pull:`11` makes pytask-latex work with pytask v0.0.9.
 
 
 0.0.7 - 2020-10-14
 ------------------
 
-- :gh:`10` fixes error that ``outputdirectory`` has to be relative to latex document due
-  to security problems.
+- :pull:`10` fixes error that ``outputdirectory`` has to be relative to latex document
+  due to security problems.
 
 
 0.0.6 - 2020-10-14
 ------------------
 
-- :gh:`9` fixes the last release and the ``pytask_collect_task_teardown`` call.
+- :pull:`9` fixes the last release and the ``pytask_collect_task_teardown`` call.
 
 
 0.0.5 - 2020-10-04
 ------------------
 
-- :gh:`5` fixes some errors in the test suite due to pytask v0.0.6.
-- :gh:`6` check that exit codes are equal to zero.
-- :gh:`7` fixes the README.
-- :gh:`8` works with pytask v0.0.7 and releases v0.0.5.
+- :pull:`5` fixes some errors in the test suite due to pytask v0.0.6.
+- :pull:`6` check that exit codes are equal to zero.
+- :pull:`7` fixes the README.
+- :pull:`8` works with pytask v0.0.7 and releases v0.0.5.
 
 
 0.0.4 - 2020-08-21
 ------------------
 
-- :gh:`4` changes the default options. latexmk will step into the source directory
+- :pull:`4` changes the default options. latexmk will step into the source directory
   before compiling the document. Releases 0.0.4.
 
 
 0.0.3 - 2020-08-12
 ------------------
 
-- :gh:`3` prepares pytask-latex for pytask v0.0.5 and releases v0.0.3.
+- :pull:`3` prepares pytask-latex for pytask v0.0.5 and releases v0.0.3.
 
 
 0.0.2 - 2020-07-22
 ------------------
 
-- :gh:`1` allowed LaTeX tasks to have more than one dependency and allows to parametrize
-  over latex options and latex documents. It also prepares release v0.0.2.
-- :gh:`2` fixes the release.
+- :pull:`1` allowed LaTeX tasks to have more than one dependency and allows to
+  parametrize over latex options and latex documents. It also prepares release v0.0.2.
+- :pull:`2` fixes the release.
 
 
 0.0.1 - 2020-07-20

README.rst

@@ -34,11 +34,12 @@
 pytask-latex
 ============
 
-pytask-latex allows you to compile LaTeX documents.
+pytask-latex allows you to compile LaTeX documents with pytask
 
-It also tries to infer the dependency of the LaTeX document such as included images,
-bibliography files and other .tex files automatically to compile LaTeX documents when it
-is possible.
+It also uses `latex-dependency-scanner
+<https://github.com/pytask-dev/latex-dependency-scanner>`_ to automatically infer the
+dependencies of the LaTeX document such as images, bibliographies and other ``.tex``
+files which are necessary to compile the LaTeX document.
 
 
 Installation
@@ -65,14 +66,14 @@ following on the command line
     $ latexmk --help
 
 If an error is shown instead of a help page, you can install ``latexmk`` with one of the
-popular LaTeX distributions, like `MiKTeX <https://miktex.org/>`_, `TeX Live
-<https://www.tug.org/texlive/>`_, `MacTeX <http://www.tug.org/mactex/>`_ or others.
+popular LaTeX distributions, like `TeX Live <https://www.tug.org/texlive/>`_, `MiKTeX
+<https://miktex.org/>`_, `MacTeX <http://www.tug.org/mactex/>`_ or others.
 
 
 Usage
 -----
 
-Here is an example where you want to compile ``document.tex`` to a PDF.
+Compiling your PDF can be as simple as writing the following task.
 
 .. code-block:: python
 
@@ -85,9 +86,9 @@ Here is an example where you want to compile ``document.tex`` to a PDF.
     def task_compile_latex_document():
         pass
 
-When the task is executed, you find a ``document.pdf`` in the same folder as your
-``document.tex``, but you could also compile the report into a another folder by
-changing the path in ``produces``.
+Use ``@pytask.mark.latex`` to indicate that this task compiles a LaTeX document.
+``@pytask.mark.depends_on`` points to the source file which is compiled and
+``@pytask.mark.produces`` is the path of the compiled PDF.
 
 
 Multiple dependencies and products
@@ -139,46 +140,82 @@ The same applies to the compiled document which is either in the first position,
 the key ``"document"`` or ``0``.
 
 
-Command Line Arguments
-~~~~~~~~~~~~~~~~~~~~~~
+Customizing the compilation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To customize the compilation, you can pass some command line arguments to ``latexmk``
-via the ``@pytask.mark.latex`` marker. The default is the following.
+pytask-latex uses latexmk by default to compile the document because it handles most
+use-cases automatically. The following is equivalent to a bare ``@pytask.mark.latex``
+decorator.
 
 .. code-block:: python
 
-    @pytask.mark.latex(["--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd"])
+    @pytask.mark.latex(compilation_steps="latexmk")
     def task_compile_latex_document():
-        pass
+        ...
+
+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 compilation_steps
+
+
+    @pytask.mark.latex(
+        compilation_steps=compilation_steps.latexmk(
+            options=("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd")
+        )
+    )
+    def task_compile_latex_document():
+        ...
 
-For example, to compile your document with XeLaTeX, use
+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(["--xelatex", "--interaction=nonstopmode"])
+    @pytask.mark.latex(
+        compilation_steps=compilation_steps.latexmk(
+            options=("--dvi", "--interaction=nonstopmode", "--synctex=1", "--cd")
+        )
+    )
     def task_compile_latex_document():
-        pass
+        ...
 
-The options ``--jobname``, ``--output-directory`` and the ``.tex`` file which will be
-compiled are automatically handled and inferred from the ``@pytask.mark.depends_on`` and
-``@pytask.mark.produces`` markers.
+``compilation_step.latexmk(options)`` generates a compilation step which is a function
+with the following signature:
 
-The ``@pytask.mark.latex`` accepts both, a string or a list of strings with options.
+.. code-block::
 
-For more options and their explanations, visit the `latexmk manual
-<https://man.cx/latexmk>`_ or type the following commands.
+    from pathlib import Path
+    import subprocess
 
-.. code-block:: console
 
-    $ latexmk -h
-    $ latexmk -showextraoptions
+    def custom_compilation_step(path_to_tex: Path, path_to_document: Path) -> None:
+        ...
+        subproces.run(..., check=True)
+
+You can also pass your custom compilation step with the same signature to the
+``compilation_steps`` keyword argument of the decorator.
+
+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 compilation steps for compiling
+bibliographies, glossaries and the like.
 
 
 Parametrization
 ~~~~~~~~~~~~~~~
 
-You can also parametrize the compilation, meaning compiling multiple .tex documents
-as well as compiling a .tex document with different command line arguments.
+You can also parametrize the compilation, meaning compiling multiple ``.tex`` documents
+as well as compiling a ``.tex`` document with different command line arguments.
 
 The following task compiles two latex documents.
 
@@ -195,7 +232,8 @@ 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``.
+``@pytask.mark.depends_on`` and ``@pytask.mark.produces``. Pass a dictionary for
+possible compilation steps and their options.
 
 .. code-block:: python
 
@@ -205,11 +243,19 @@ to include the latex decorator in the parametrization just like with
         [
             (
                 "document.pdf",
-                ("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd"),
+                {
+                    "compilation_steps": compilation_steps.latexmk(
+                        ("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd")
+                    )
+                },
             ),
             (
                 "document.dvi",
-                ("--dvi", "--interaction=nonstopmode", "--synctex=1", "--cd"),
+                {
+                    "compilation_steps": compilation_steps.latexmk(
+                        ("--dvi", "--interaction=nonstopmode", "--synctex=1", "--cd")
+                    )
+                },
             ),
         ],
     )

environment.yml

@@ -19,7 +19,6 @@ dependencies:
   - black
   - jupyterlab
   - matplotlib
-  - pdbpp
   - pre-commit
   - pytest
   - pytest-cov