142 lines
4.7 KiB
ReStructuredText
142 lines
4.7 KiB
ReStructuredText
.. python-docx-template documentation master file, created by
|
||
sphinx-quickstart on Thu Mar 12 17:32:17 2015.
|
||
You can adapt this file completely to your liking, but it should at least
|
||
contain the root `toctree` directive.
|
||
|
||
Welcome to python-docx-template's documentation!
|
||
================================================
|
||
|
||
.. rubric:: Quickstart
|
||
|
||
To install::
|
||
|
||
pip install docxtpl
|
||
|
||
Usage::
|
||
|
||
from docxtpl import DocxTemplate
|
||
|
||
doc = DocxTemplate("my_word_template.docx")
|
||
context = { 'company_name' : 'World company" }
|
||
doc.render(context)
|
||
doc.save("generated_doc.docx")
|
||
|
||
Introduction
|
||
------------
|
||
|
||
This package uses 2 major packages :
|
||
|
||
- python-docx for reading, writing and creating sub documents
|
||
- jinja2 for managing tags inserted into the template docx
|
||
|
||
python-docx-template has been created because python-docx is powerful for creating documents but not for modifying them.
|
||
|
||
The idea is to begin to create an exemple of the document you want to generate with microsoft word, it can be as complex as you want :
|
||
pictures, index tables, footer, header, variables, anything you can do with word.
|
||
Then, as you are still editing the document with microsoft word, you insert jinja2-like tags directly in the document.
|
||
You save the document as a .docx file (xml format) : it will be your .docx template file.
|
||
|
||
Now you can use python-docx-template to generate as many word documents you want from this .docx template and context variables you will associate.
|
||
|
||
Jinja2-like syntax
|
||
------------------
|
||
|
||
As the Jinja2 package is used, one can use all jinja2 tags and filters inside the word document.
|
||
Nevertheless there are some restrictions and extensions to make it work inside a word document:
|
||
|
||
Restrictions
|
||
++++++++++++
|
||
|
||
The usual jinja2 tags, are only to be used inside a same run of a same paragraph, it can not be used across several paragraphs, table rows, runs.
|
||
|
||
Note : a 'run' for microsoft word is a sequence of characters with the same style. For exemple, if you create a paragraph with all characters the same style :
|
||
word will create internally only one 'run' in the paragraph. Now, if you put in bold a text in the middle of this paragraph, word will transform the previous 'run' into 3 'runs' (normal - bold - normal).
|
||
|
||
Extensions
|
||
++++++++++
|
||
|
||
Tags
|
||
....
|
||
|
||
In order to manage paragraphs, table rows, runs, special syntax has to be used ::
|
||
|
||
{%p jinja2_tag %} for paragraphs
|
||
{%tr jinja2_tag %} for table rows
|
||
{%r jinja2_tag %} for runs
|
||
|
||
By using these tags, python-docx-template will take care to put the real jinja2 tags at the right place into the document's xml source code.
|
||
In addition, these tags also tells python-docx-template to remove the paragraph, table row or run where are located the begin and ending tags and only takes care about what is in between.
|
||
|
||
Display variables
|
||
.................
|
||
|
||
As part of jinja2, one can used double braces::
|
||
|
||
{{ <var> }}
|
||
|
||
But if `<var>` is an RichText object, you must specify that you are changing the actual 'run' ::
|
||
|
||
{{r <var> }}
|
||
|
||
Note the 'r' right after the openning braces
|
||
|
||
Cell color
|
||
..........
|
||
|
||
There is a special case when you want to change the background color of a table cell, you must put the following tag at the very beginning of the cell ::
|
||
|
||
{% cellbg <var> %}
|
||
|
||
`<var>` must contain the color's hexadecimal code *without* the hash sign
|
||
|
||
Escaping
|
||
........
|
||
|
||
In order to display `{%`, `%}`, `{{` or `}}`, one can use ::
|
||
|
||
{_%, %_}, {_{ or }_}
|
||
|
||
Sub-documents
|
||
-------------
|
||
|
||
A template variable can contain a complex and built from scratch with python-docx word document.
|
||
To do so, get first a sub-document object from template object and use it as a python-docx document object, see exemple in `tests/subdoc.py`.
|
||
|
||
RichText
|
||
--------
|
||
|
||
When you use `{{ <var> }}` tag in your template, it will be remplaced by the string contained within `var` variable.
|
||
BUT it will keep the current style.
|
||
If you want to add dynamically changeable style, you have to use both : the `{{r <var> }}` tag AND a RichText object within `var` variable.
|
||
You can change color, bold, italic, size and so on, but the best way is to use Microsoft Word to define your own *caracter* style
|
||
( Home tab -> modify style -> manage style button -> New style, select ‘Character style’ in the form ), see exemple in `tests/richtext.py`
|
||
|
||
|
||
Examples
|
||
--------
|
||
|
||
The best way to see how it works is to read exemples, they are located in `tests/` directory. Templates and generated .docx files are in `tests/test_files/`.
|
||
|
||
|
||
|
||
|
||
.. rubric:: Functions index
|
||
|
||
.. currentmodule:: docxtpl
|
||
|
||
.. to list all function : grep "def " *.py | sed -e 's,^def ,,' -e 's,(.*,,' | sort
|
||
|
||
.. rubric:: Functions documentation
|
||
|
||
.. automodule:: docxtpl
|
||
:members:
|
||
|
||
|
||
Indices and tables
|
||
==================
|
||
|
||
* :ref:`genindex`
|
||
* :ref:`modindex`
|
||
* :ref:`search`
|
||
|