Skip to main content

Compile LaTeX documents with pytask.

Project description

pytask-latex

PyPI PyPI - Python Version image image PyPI - License image image pre-commit.ci status image


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.

Installation

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.

Usage

Compiling your PDF can be as simple as writing the following task.

from pathlib import Path
from pytask import mark


@mark.latex(script=Path("document.tex"), document=Path("document.pdf"))
def task_compile_latex_document():
    pass

Use @mark.latex to indicate that this task compiles a LaTeX document. The script and the document keywords provide absolute paths or paths relative to the task module to the LaTeX file and the compiled document.

Dependencies and Products

Dependencies and products can be added as usual. Read this tutorial.

For example, with the @task decorator. (The choice of the kwarg name, here path, is arbitrary.)

from pytask import mark
from pytask import task
from pathlib import Path


@task(kwargs={"path": Path("path_to_another_dependency.tex")})
@mark.latex(script=Path("document.tex"), document=Path("document.pdf"))
def task_compile_latex_document():
    pass

Customizing the compilation

pytask-latex uses latexmk by default to compile the document because it handles most use-cases automatically. The following is equivalent to a bare @mark.latex decorator.

@mark.latex(
    script=Path("document.tex"),
    document=Path("document.pdf"),
    compilation_steps="latexmk",
)
def task_compile_latex_document():
    ...

The @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


@mark.latex(
    script=Path("document.tex"),
    document=Path("document.pdf"),
    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.

@mark.latex(
    script=Path("document.tex"),
    document=Path("document.pdf"),
    compilation_steps=cs.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.

Repeating tasks with different scripts or inputs

You can compile multiple LaTeX documents as well as compiling a single .tex document with different command line arguments.

The following task compiles two latex documents.

for i in range(2):

    @task
    @mark.latex(script=Path(f"document_{i}.tex"), document=Path(f"document_{i}.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. Pass a dictionary for possible compilation steps and their options.

for format_ in ("pdf", "dvi"):

    @task
    @mark.latex(
        script=Path("document.tex"),
        document=Path(f"document.{format_}"),
        compilation_steps=cs.latexmk(
            (f"--{format_}", "--interaction=nonstopmode", "--synctex=1", "--cd")
        ),
    )
    def task_compile_latex_document():
        pass

Configuration

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.

[tool.pytask.ini_options]
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.

Changes

Consult the release notes to find out about what is new.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytask_latex-0.4.2.tar.gz (15.6 kB view details)

Uploaded Source

Built Distribution

pytask_latex-0.4.2-py3-none-any.whl (12.2 kB view details)

Uploaded Python 3

File details

Details for the file pytask_latex-0.4.2.tar.gz.

File metadata

  • Download URL: pytask_latex-0.4.2.tar.gz
  • Upload date:
  • Size: 15.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.18

File hashes

Hashes for pytask_latex-0.4.2.tar.gz
Algorithm Hash digest
SHA256 a92fd1267583b506cc1d5db9c16e64d54bb8d0de9d54dbdd48451fbca7e28a57
MD5 3f8195b0e439bf959ea75f6f9e068411
BLAKE2b-256 01e23018bd184797d6ce137de99b732aaa9995d3572f04eda507b67986e0e78a

See more details on using hashes here.

File details

Details for the file pytask_latex-0.4.2-py3-none-any.whl.

File metadata

  • Download URL: pytask_latex-0.4.2-py3-none-any.whl
  • Upload date:
  • Size: 12.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.18

File hashes

Hashes for pytask_latex-0.4.2-py3-none-any.whl
Algorithm Hash digest
SHA256 df78fa7f70abc14075b60bcadb41d83e2d108deaeb403530bc0a502723b9bfb9
MD5 0e004b1cfce20ebae64c549a2de64c3c
BLAKE2b-256 be39395f77f67b0ea46245ff509d2aefa9fe7cc6c611f165874724e99f02e505

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page