Reorganize documentation
This commit is contained in:
Eric Lapouyade
parent
650b28d852
commit
1a4a5f5723
@ -1,6 +1,7 @@
|
||||
0.16.4 (2022-08-04)
|
||||
-------------------
|
||||
- Regional fonts for RichText
|
||||
- Reorganize documentation
|
||||
|
||||
0.16.3 (2022-07-14)
|
||||
-------------------
|
||||
|
||||
211
docs/index.rst
211
docs/index.rst
@ -62,67 +62,100 @@ MS 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 different 'runs' (normal - bold - normal).
|
||||
|
||||
**Important:**
|
||||
|
||||
Always put space after a jinja2 starting var/tag delimiter and a space before the ending one :
|
||||
|
||||
Avoid::
|
||||
|
||||
{{myvariable}}
|
||||
{%if something%}
|
||||
|
||||
Use instead::
|
||||
|
||||
{{ myvariable }}
|
||||
{% if something %}
|
||||
|
||||
Get Defined Variables
|
||||
+++++++++++++++++++++
|
||||
|
||||
In order to get the missing variables after rendering use ::
|
||||
|
||||
tpl=DocxTemplate('your_template.docx')
|
||||
tpl.render(context_dict)
|
||||
set_of_variables = tpl.get_undeclared_template_variables()
|
||||
|
||||
**IMPORTANT** : You may use the method before rendering to get a set of keys you need, e.g. to be prompted to a user or written in a file for manual processing.
|
||||
|
||||
Extensions
|
||||
++++++++++
|
||||
|
||||
Tags
|
||||
....
|
||||
|
||||
In order to manage paragraphs, table rows, table columns, runs, special syntax has to be used ::
|
||||
In order to manage paragraphs, table rows, table columns, runs, special syntax has to be used::
|
||||
|
||||
{%p jinja2_tag %} for paragraphs
|
||||
{%tr jinja2_tag %} for table rows
|
||||
{%tc jinja2_tag %} for table columns
|
||||
{%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 tell python-docx-template to **remove** the paragraph, table row, table column or run where the begin and ending tags are located and only takes care about what is in between.
|
||||
By using these tags, python-docx-template will take care to put the real jinja2 tags (without the `p`, `tr`, `tc` or `r`) at the right place into the document's xml source code.
|
||||
In addition, these tags also tell python-docx-template to **remove** the paragraph, table row, table column or run where the tags are located.
|
||||
|
||||
For example, if you have this kind of template::
|
||||
|
||||
{%p if display_paragraph %}
|
||||
One or many paragraphs
|
||||
{%p endif %}
|
||||
|
||||
The first and last paragraphs (those containing ``{%p ... %}`` tags) will never appear in generated docx, regardless of the ``display_paragraph`` value.
|
||||
|
||||
Here only::
|
||||
|
||||
One or many paragraphs
|
||||
|
||||
will appear in generated docx if ``display_paragraph`` is True, otherwise, no paragraph at all are displayed.
|
||||
|
||||
**IMPORTANT :** Always put space after a starting tag delimiter and a space before the ending one :
|
||||
|
||||
Avoid::
|
||||
|
||||
{%if something%}
|
||||
{%pif display_paragraph%}
|
||||
|
||||
Use instead::
|
||||
|
||||
{% if something %}
|
||||
{%p if display_paragraph %}
|
||||
|
||||
**IMPORTANT** : Do not use ``{%p``, ``{%tr``, ``{%tc`` or ``{%r`` twice in the same
|
||||
paragraph, row, column or run. Example :
|
||||
|
||||
Do not use this ::
|
||||
Do not use this::
|
||||
|
||||
{%p if display_paragraph %}Here is my paragraph {%p endif %}
|
||||
|
||||
But use this instead in your docx template ::
|
||||
But use this instead in your docx template::
|
||||
|
||||
{%p if display_paragraph %}
|
||||
Here is my paragraph
|
||||
{%p endif %}
|
||||
|
||||
This syntax is possible because MS Word considers each line as a new paragraph and
|
||||
``{%p`` tags are not in the same paragraph in the second case.
|
||||
This syntax is possible because MS Word considers each line as a new paragraph (if you do not use CTRL-RETURN).
|
||||
|
||||
Display variables
|
||||
.................
|
||||
|
||||
As part of jinja2, one can used double braces::
|
||||
|
||||
{{ <var> }}
|
||||
|
||||
if ``<var>`` is a string, ``\n``, ``\a``, ``\t`` and ``\f`` will be translated respectively into newlines, new paragraphs, tabs and page breaks
|
||||
|
||||
But if ``<var>`` is a RichText_ object, you must specify that you are changing the actual 'run'::
|
||||
|
||||
{{r <var> }}
|
||||
|
||||
Note the ``r`` right after the opening braces.
|
||||
|
||||
**VERY IMPORTANT :** Variables must not contains characters like ``<``, ``>`` and ``&`` unless using Escaping_
|
||||
|
||||
**IMPORTANT :** Always put space after a starting var delimiter and a space before the ending one :
|
||||
|
||||
Avoid::
|
||||
|
||||
{{myvariable}}
|
||||
{{rmyrichtext}}
|
||||
|
||||
Use instead::
|
||||
|
||||
{{ myvariable }}
|
||||
{{r myrichtext }}
|
||||
|
||||
**IMPORTANT** : Do not use 2 times ``{{r`` in the same run. Use RichText.add()
|
||||
method to concatenate several strings and styles at python side and only one
|
||||
``{{r`` at template side.
|
||||
|
||||
Comments
|
||||
........
|
||||
|
||||
You can add jinja-like comments in your template ::
|
||||
You can add jinja-like comments in your template::
|
||||
|
||||
{#p this is a comment as a paragraph #}
|
||||
{#tr this is a comment as a table row #}
|
||||
@ -130,15 +163,6 @@ You can add jinja-like comments in your template ::
|
||||
|
||||
See tests/templates/comments_tpl.docx for an example.
|
||||
|
||||
Multiple rendering
|
||||
..................
|
||||
|
||||
Since v0.15.0, it is possible to create ``DocxTemplate`` object once and call
|
||||
``render(context)`` several times. Note that if you want to use replacement
|
||||
methods like ``replace_media()``, ``replace_embedded()`` and/or ``replace_zipname()``
|
||||
during multiple rendering, you will have to call ``reset_replacements()``
|
||||
at rendering loop start.
|
||||
|
||||
Split and merge text
|
||||
....................
|
||||
|
||||
@ -163,33 +187,35 @@ One can use *ENTER* or *SHIFT+ENTER* to split a text like below, then use ``{%-`
|
||||
|
||||
**IMPORTANT 2 :** ``{%- xxx -%}`` tags must be alone in a line : do not add some text before or after on the same line.
|
||||
|
||||
Escaping delimiters
|
||||
...................
|
||||
|
||||
Display variables
|
||||
.................
|
||||
In order to display ``{%``, ``%}``, ``{{`` or ``}}``, one can use::
|
||||
|
||||
As part of jinja2, one can used double braces::
|
||||
{_%, %_}, {_{ or }_}
|
||||
|
||||
{{ <var> }}
|
||||
Tables
|
||||
......
|
||||
|
||||
if ``<var>`` is a string, ``\n``, ``\a``, ``\t`` and ``\f`` will be translated respectively into newlines, new paragraphs, tabs and page breaks
|
||||
Spanning
|
||||
~~~~~~~~
|
||||
|
||||
But if ``<var>`` is a RichText_ object, you must specify that you are changing the actual 'run'::
|
||||
You can span table cells horizontally in two ways, by using ``colspan`` tag (see tests/dynamic_table.py)::
|
||||
|
||||
{{r <var> }}
|
||||
{% colspan <var> %}
|
||||
|
||||
Note the ``r`` right after the opening braces.
|
||||
`<var>` must contain an integer for the number of columns to span. See tests/test_files/dynamic_table.py for an example.
|
||||
|
||||
**IMPORTANT** : Do not use the ``r`` variable in your template because ``{{r}}`` could be interpreted as a ``{{r``
|
||||
without variable specified. Nevertheless, you can use a bigger variable name starting
|
||||
with 'r'. For example ``{{render_color}}`` will be interpreted as ``{{ render_color }}`` not as ``{{r ender_color}}``.
|
||||
You can also span horizontally within a for loop (see tests/horizontal_merge.py)::
|
||||
|
||||
**IMPORTANT** : Do not use 2 times ``{{r`` in the same run. Use RichText.add()
|
||||
method to concatenate several strings and styles at python side and only one
|
||||
``{{r`` at template side.
|
||||
{% hm %}
|
||||
|
||||
You can also merge cells vertically within a for loop (see tests/vertical_merge.py)::
|
||||
|
||||
{% vm %}
|
||||
|
||||
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::
|
||||
|
||||
@ -197,24 +223,6 @@ There is a special case when you want to change the background color of a table
|
||||
|
||||
`<var>` must contain the color's hexadecimal code *without* the hash sign
|
||||
|
||||
Column spanning
|
||||
...............
|
||||
|
||||
If you want to dynamically span a table cell over many column (this is useful when you have a table with a dynamic column count),
|
||||
you must put the following tag at the very beginning of the cell to span::
|
||||
|
||||
{% colspan <var> %}
|
||||
|
||||
`<var>` must contain an integer for the number of columns to span. See tests/test_files/dynamic_table.py for an example.
|
||||
|
||||
Escaping
|
||||
........
|
||||
|
||||
In order to display ``{%``, ``%}``, ``{{`` or ``}}``, one can use::
|
||||
|
||||
{_%, %_}, {_{ or }_}
|
||||
|
||||
|
||||
.. _RichText:
|
||||
|
||||
RichText
|
||||
@ -227,6 +235,9 @@ You can change color, bold, italic, size, font and so on, but the best way is to
|
||||
( Home tab -> modify style -> manage style button -> New style, select ‘Character style’ in the form ), see example in `tests/richtext.py`
|
||||
Instead of using ``RichText()``, one can use its shortcut : ``R()``
|
||||
|
||||
The ``RichText()`` or ``R()`` offers newline, new paragraph, and page break features : just use ``\n``, ``\a``, ``\t`` or ``\f`` in the
|
||||
text, they will be converted accordingly.
|
||||
|
||||
There is a specific case for font: if your font is not displayed correctly, it may be because it is defined
|
||||
only for a region. To know your region, it requires a little work by analyzing the document.xml inside the docx template (this is a zip file).
|
||||
To specify a region, you have to prefix your font name this that region and a column::
|
||||
@ -279,10 +290,14 @@ calling method `new_subdoc()` ::
|
||||
|
||||
see `tests/merge_docx.py` for full code
|
||||
|
||||
Escaping, newline, new paragraph, Listing
|
||||
-----------------------------------------
|
||||
.. _Escaping:
|
||||
|
||||
When you use a ``{{ <var> }}``, you are modifying an **XML** word document, this means you cannot use all chars,
|
||||
Escaping
|
||||
--------
|
||||
|
||||
By default, no escaping is done : read carefully this chapter if you want to avoid crashes during docx generation.
|
||||
|
||||
When you use a ``{{ <var> }}``, under the hood, you are modifying an **XML** word document, this means you cannot use all chars,
|
||||
especially ``<``, ``>`` and ``&``. In order to use them, you must escape them. There are 4 ways :
|
||||
|
||||
* ``context = { 'var':R('my text') }`` and ``{{r <var> }}`` in the template (note the ``r``),
|
||||
@ -290,12 +305,9 @@ especially ``<``, ``>`` and ``&``. In order to use them, you must escape them. T
|
||||
* ``context = { 'var':escape('my text')}`` and ``{{ <var> }}`` in the template.
|
||||
* enable autoescaping when calling render method: ``tpl.render(context, autoescape=True)`` (default is autoescape=False)
|
||||
|
||||
The ``RichText()`` or ``R()`` offers newline, new paragraph, and page break features : just use ``\n``, ``\a``, ``\t`` or ``\f`` in the
|
||||
text, they will be converted accordingly.
|
||||
|
||||
See tests/escape.py example for more informations.
|
||||
|
||||
Another solution, if you want to include a listing into your document, that is to escape the text and manage \n, \a, and \f
|
||||
Another solution, if you want to include a listing into your document, that is to escape the text and manage ``\n``, ``\a``, and ``\f``
|
||||
you can use the ``Listing`` class :
|
||||
|
||||
in your python code::
|
||||
@ -303,6 +315,7 @@ in your python code::
|
||||
context = { 'mylisting':Listing('the listing\nwith\nsome\nlines \a and some paragraph \a and special chars : <>&') }
|
||||
|
||||
in your docx template just use ``{{ mylisting }}``
|
||||
|
||||
With ``Listing()``, you will keep the current character styling (except after a ``\a`` as you start a new paragraph).
|
||||
|
||||
Replace docx pictures
|
||||
@ -368,6 +381,26 @@ The zipname starts with "word/embeddings/". Note that the file to be replaced is
|
||||
This works for embedded MSWord file like Excel or PowerPoint file, but won't work for others like PDF, Python or even Text files :
|
||||
For these ones, MSWord generate an oleObjectNNN.bin file which is no use to be replaced as it is encoded.
|
||||
|
||||
Get Defined Variables
|
||||
---------------------
|
||||
|
||||
In order to get the missing variables after rendering use ::
|
||||
|
||||
tpl=DocxTemplate('your_template.docx')
|
||||
tpl.render(context_dict)
|
||||
set_of_variables = tpl.get_undeclared_template_variables()
|
||||
|
||||
**IMPORTANT** : You may use the method before rendering to get a set of keys you need, e.g. to be prompted to a user or written in a file for manual processing.
|
||||
|
||||
Multiple rendering
|
||||
------------------
|
||||
|
||||
Since v0.15.0, it is possible to create ``DocxTemplate`` object once and call
|
||||
``render(context)`` several times. Note that if you want to use replacement
|
||||
methods like ``replace_media()``, ``replace_embedded()`` and/or ``replace_zipname()``
|
||||
during multiple rendering, you will have to call ``reset_replacements()``
|
||||
at rendering loop start.
|
||||
|
||||
|
||||
|
||||
Microsoft Word 2016 special cases
|
||||
@ -388,20 +421,6 @@ And in your template, use the {{r notation::
|
||||
{{r test_space_r}} Spaces will be preserved
|
||||
{{r test_tabs_r}} Tabs will be displayed
|
||||
|
||||
Tables
|
||||
------
|
||||
|
||||
You can span table cells horizontally in two ways, by using ``colspan`` tag (see tests/dynamic_table.py)::
|
||||
|
||||
{% colspan <number of column to span> %}
|
||||
|
||||
or within a for loop (see tests/horizontal_merge.py)::
|
||||
|
||||
{% hm %}
|
||||
|
||||
You can also merge cells vertically within a for loop (see tests/vertical_merge.py)::
|
||||
|
||||
{% vm %}
|
||||
|
||||
Jinja custom filters
|
||||
--------------------
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user