Creating DOCX
=============
.. External references

.. _faker-file: https://pypi.org/project/faker-file/

The goal of this library is to help you out with basic tasks. You can easily
generate DOCX files with 100 pages (paper size is A4), having a little text
on each.

If you don't like how DOCX files are generated by this library, you can
check the `faker-file`_ package, which can produce complex DOCX documents.

If you need bytes
-----------------

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_docx/docx_bytes_1.py
        :language: python
        :lines: 1-3

    *See the full example*
    :download:`here <_static/examples/creating_docx/docx_bytes_1.py>`

The generated DOCX will consist of a single page with little text on it.

If you want to control number of pages created, you could:

- Pass the list of texts to be used in ``texts`` argument.
- Pass the number of pages to be created in ``nb_pages`` argument.

----

See the example below for ``texts`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_docx/docx_bytes_2.py
        :language: python
        :lines: 3-

    *See the full example*
    :download:`here <_static/examples/creating_docx/docx_bytes_2.py>`

----

See the example below for ``nb_pages`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_docx/docx_bytes_3.py
        :language: python
        :lines: 3-

    *See the full example*
    :download:`here <_static/examples/creating_docx/docx_bytes_3.py>`

If you need files
-----------------
.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_docx/docx_file_1.py
        :language: python
        :lines: 3-

    *See the full example*
    :download:`here <_static/examples/creating_docx/docx_file_1.py>`

----

With ``texts`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_docx/docx_file_2.py
        :language: python
        :lines: 3-

    *See the full example*
    :download:`here <_static/examples/creating_docx/docx_file_2.py>`

----

With ``nb_pages`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_docx/docx_file_3.py
        :language: python
        :lines: 3-

    *See the full example*
    :download:`here <_static/examples/creating_docx/docx_file_3.py>`

----

Using text templates:

.. code-block:: python
    :name: test_text_templates

    from fake import FAKER, StringTemplate

    template = """
    {date(start_date='-7d')}
    {name}
    {sentence(nb_words=2, suffix='')} {pyint(min_value=1, max_value=99)}
    {randomise_string(value='#### ??', digits='123456789')} {city}

    Dear friend,

    {text(nb_chars=1000, allow_overflow=True)}

    Sincerely yours,

    {name}
    {email}
    {domain_name}
    """
    # DOCX file of 1 page
    docx_file_1 = FAKER.docx_file(
        texts=[StringTemplate(template)],
    )
    # DOCX file of 10 pages
    docx_file_10 = FAKER.docx_file(
        texts=[StringTemplate(template) for _ in range(10)],
    )

----
