Generateurv2/backend/env/lib/python3.10/site-packages/django_tex-1.1.10.dist-info/METADATA

Metadata-Version: 2.1
Name: django-tex
Version: 1.1.10
Summary: A simple Django app to render Latex templates and compile them into PDF files.
Home-page: https://github.com/weinbusch/django-tex
Author: Martin Bierbaum
License: MIT
Keywords: django latex jinja2
Platform: UNKNOWN
Requires-Python: >=3.6.2
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: django (>=2.2)
Requires-Dist: jinja2 (>=2.9)

# django-tex

django-tex is a simple Django app to render LaTeX templates and compile
them into PDF files.

Django-tex requires a local LaTeX installation and uses the jinja2 
templating engine for template rendering.

## Installation

`django-tex` is available on [pypi.org](https://pypi.org/project/django-tex/). It can be installed by:

```pip install django_tex```

## Quick start

1. Add "django_tex" to your `INSTALLED_APPS` setting:

```python
INSTALLED_APPS = [
    ...
    'django_tex',
]
```

2. Configure a template engine named `tex` in settings.py:

```python
TEMPLATES = [
    {
        'NAME': 'tex',
        'BACKEND': 'django_tex.engine.TeXEngine', 
        'APP_DIRS': True,
    },
]
```

3. Create a LaTeX template in your template directory:

```tex
# test.tex
\documentclass{article}

\begin{document}

\section{ {{- foo -}} }

\end{document}
```

4. Use "compile_template_to_pdf" in your code to get the PDF file as a bytes object:

```python
from django_tex.core import compile_template_to_pdf

template_name = 'test.tex'
context = {'foo': 'Bar'}
PDF = compile_template_to_pdf(template_name, context)
```

Or use `render_to_pdf` to generate a HTTPResponse containing the PDF file:

```python
from django_tex.shortcuts import render_to_pdf

def view(request):
    template_name = 'test.tex'
    context = {'foo': 'Bar'}
    return render_to_pdf(request, template_name, context, filename='test.pdf')
```

## Some notes on usage

### Latex binary

The default LaTeX interpreter is set to `lualatex`. This can be changed by the setting
`LATEX_INTERPRETER`, for instance: `LATEX_INTERPRETER = 'pdflatex'`. Of course, the interpreter needs
to be installed on your system for `django-tex` to work properly.

### Interpreter arguments

You can pass additional arguments to the latex interpreter by using the `LATEX_INTERPRETER_OPTIONS` setting.

### Whitespace control

Since django-tex uses jinja, you can use jinja's whitespace control in 
LaTeX templates. For example, `\section{ {{ foo }} }` would be rendered as 
`\section{ Bar }` with the above context; `\section{ {{- foo -}} }`, however, 
gets rendered nicely as `\section{Bar}`.

### Built-in filters

Django's built-in filters are available. So you can use `{{ foo|date('d. F Y') }}` 
to get `1. Januar 2018`, for instance.

Further, django-tex adds the custom filter `localize` to the jinja environment.
This runs its input through `django.utils.formats.localize_input` to
create a localized representation. The output depends on the `USE_L10N` and `LANGUAGE_CODE`
settings. Use the filter like this: `{{ foo|localize }}`.

If you want to convert linebreaks into LaTeX linebreaks (`\\`), use the `linebreaks` filter (`{{ foo | linebreaks }}`).
### Escaping LaTeX special characters

To escape LaTeX special characters, use the `latex_escape` filter, i.e. `{{ foo | latex_escape }}`s. 
This escapes the following characters: `&$%#_{}\^~` 
([see also this SO question](https://tex.stackexchange.com/questions/34580/escape-character-in-latex))
Using this filter all printable character should lead to a successful LaTeX build.
Spacing for the characters `\^~` is automatically adopted as an end user would expect it.

Please note Jinja's autoescaping is turned off in the default `django-tex` environment.

### Custom filters

Custom filters can be defined as explained in  the jinja documentation [here](http://jinja.pocoo.org/docs/2.10/api/#custom-filters). For example, the following filter formats a
`datetime.timedelta` object as a hh:mm string:

```python
def hhmm_format(value):
    total_seconds = value.total_seconds()
    hours, remainder = divmod(total_seconds, 3600)
    minutes, seconds = divmod(remainder, 60)
    return '{:n}:{:02n}'.format(hours, minutes)
```

The filter has to be added to a custom environment and the `django-tex` templating engine has to be made aware
of the environment. This can be achieved, for example, by defining a custom environment callable in an `environment.py` module in your app:

```python
# environment.py
from django_tex.environment import environment

def hhmm_format(value):
    pass # as above

def my_environment(**options):
    env = environment(**options)
    env.filters.update({
        'hhmm_format': hhmm_format
    })
    return env
```

... and passing the dotted path to `my_environment` to the `TEMPLATES` settings:

```python
# settings.py

TEMPLATES = [
    {
        'NAME': 'tex',
        'BACKEND': 'django_tex.engine.TeXEngine', 
        'APP_DIRS': True,
        'OPTIONS': {
            'environment': 'myapp.environment.my_environment',
        }
    },
]
```

### Including graphics files

Graphics can be included in LaTeX documents using the `\includegraphics{<filename>}` command provided
by the `graphicx` package. Normally, LaTeX looks for graphics files in the current working directory, i.e. the 
directory including the source `.tex` file. The problem here is that `django-tex` creates a temporary directory to
store the source file so that the LaTeX compiler does not see any graphics files provided by the Django application.
This problem can be solved by specifying the absolute path to one or more directories including the graphics files 
using the `\graphicspath` command.

`Django-tex` allows the user to specify the absolute paths to one or more directories in the `LATEX_GRAPHICSPATH` 
setting. This setting should contain a list of one or more paths:

```python
# settings.py

LATEX_GRAPHICSPATH = ['c:\foo\bar', 'c:\bar\foo']
```

Of course, a good way of constructing those paths is to use `os.path.join(BASE_DIR, <path>)`.

Using the template tag `{% graphicspath %}`, the correct `\graphicspath` command can be inserted into the `.tex` 
template. In the above case, `{% graphicspath %}` turns into `\graphicspath{ {"c:/foo/bar/"} {"c:/bar/foo/"} }`. Use  
`{% graphicspath %}` like this:

```
\documentclass{article}
\usepackage{graphicx}

{% graphicspath %}

\begin{document}

\includegraphics{foo}

\end{document}
```

If `LATEX_GRAPHICSPATH` is not specified, `django-tex` takes the `BASE_DIR` instead.

Note: There might be a problem if the path to the graphics directory contains whitespaces. To my knowledge, `lualatex` cannot handle whitespaces in the `\graphicspath` command, but `pdflatex` can.