pytask-latex allows you to compile LaTeX documents with pytask
It also uses 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.
pytask-latex is available on PyPI and Anaconda.org. Install it with
$ pip install pytask-latex
# or
$ conda install -c conda-forge pytask-latex
You also need to have latexmk
installed which determines the necessary number of
compilation steps (here is an
explanation for what latexmk achieves). To test whether it is installed, type the
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 TeX Live, MiKTeX, MacTeX or others.
Compiling your PDF can be as simple as writing the following task.
import pytask
@pytask.mark.latex
@pytask.mark.depends_on("document.tex")
@pytask.mark.produces("document.pdf")
def task_compile_latex_document():
pass
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.
In general, you might not need to add dependencies other than the main LaTeX file
because pytask-latex tries to infer other dependencies automatically. See the
explanation for infer_latex_dependencies
below.
What happens if you need to add more dependencies to a task because they are not found automatically? You could use a list, but ensure that the LaTeX document which should be compiled is in the first position of the list.
@pytask.mark.latex
@pytask.mark.depends_on(["document.tex", "image.png"])
@pytask.mark.produces("document.pdf")
def task_compile_latex_document():
pass
If you use a dictionary to pass dependencies to the task, pytask-latex will, first, look
for a "source"
key in the dictionary and, secondly, under the key 0
.
@pytask.mark.depends_on({"source": "document.tex", "image": "image.png"})
def task_compile_document():
pass
# or
@pytask.mark.depends_on({0: "document.tex", "image": "image.png"})
def task_compile_document():
pass
# or two decorators for the function, if you do not assign a name to the image.
@pytask.mark.depends_on({"source": "document.tex"})
@pytask.mark.depends_on("image.png")
def task_compile_document():
pass
The same applies to the compiled document which is either in the first position, under
the key "document"
or 0
.
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.
@pytask.mark.latex(compilation_steps="latexmk")
def task_compile_latex_document():
...
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.
from pytask_latex import compilation_steps as cs @pytask.mark.latex( compilation_steps=cs.latexmk( options=("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd") ) ) def task_compile_latex_document(): ...
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
.
@pytask.mark.latex(
compilation_steps=compilation_steps.latexmk(
options=("--dvi", "--interaction=nonstopmode", "--synctex=1", "--cd")
)
)
def task_compile_latex_document():
...
compilation_step.latexmk(options)
generates a compilation step which is a function
with the following signature:
from pathlib import Path import subprocess 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.
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.
@pytask.mark.latex
@pytask.mark.parametrize(
"depends_on, produces",
[("document_1.tex", "document_1.pdf"), ("document_2.tex", "document_2.pdf")],
)
def task_compile_latex_document():
pass
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 compilation steps and their options.
@pytask.mark.depends_on("document.tex")
@pytask.mark.parametrize(
"produces, latex",
[
(
"document.pdf",
{
"compilation_steps": compilation_steps.latexmk(
("--pdf", "--interaction=nonstopmode", "--synctex=1", "--cd")
)
},
),
(
"document.dvi",
{
"compilation_steps": compilation_steps.latexmk(
("--dvi", "--interaction=nonstopmode", "--synctex=1", "--cd")
)
},
),
],
)
def task_compile_latex_document():
pass
- latex_source_key
If you want to change the name of the key which identifies the source file, change the following default configuration in your pytask configuration file.
latex_source_key = source
- latex_document_key
If you want to change the name of the key which identifies the compiled document, change the following default configuration in your pytask configuration file.
latex_source_key = source
- infer_latex_dependencies
pytask-latex tries to scan your LaTeX document for included files with the help of latex-dependency-scanner if the following configuration value is true which is also the default.
infer_latex_dependencies = true
Since the package is in its early development phase and LaTeX provides a myriad of ways to include files as well as providing shortcuts for paths (e.g.,
\graphicspath
), there are definitely some rough edges left. File an issue here or in the other project in case of a problem.
Consult the release notes to find out about what is new.