Examples
********

In the examples below, the fake.py package is used for demonstration
purposes.


"jsphinx-download" directive usage
==================================


Example 1
---------

See the following full functional snippet for generating a "DOCX"
file.

   # Required imports
   from fake import FAKER

   # Generate DOCX file
   docx_file = FAKER.docx_file()

*See the full example* "here"

======================================================================

The documentation snippet, the above (Example 1) code was rendered
from:

*Filename: example.rst*

   See the following full functional snippet for generating a ``DOCX`` file.

   .. container:: jsphinx-download

       .. literalinclude:: examples/simple/snippet_1.py
           :language: python
           :lines: 1-5

       *See the full example*
       :download:`here <examples/simple/snippet_1.py>`

======================================================================


Example 2
---------

See the example below for "nb_pages" tweak:

   # Generate DOCX file of 100 pages
   docx_file = FAKER.docx_file(nb_pages=100)

*See the full example* "here"

======================================================================

The documentation snippet, the above (Example 2) code was rendered
from:

*Filename: example.rst*

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

   .. container:: jsphinx-download

       .. literalinclude:: examples/simple/snippet_2.py
           :language: python
           :lines: 4-5

       *See the full example*
       :download:`here <examples/simple/snippet_2.py>`

======================================================================


Example 3
---------

See the example below for "texts" tweak:

   # Generate DOCX file of 3 pages with custom texts
   docx_file = FAKER.docx_file(texts=["1st page", "2nd page", "3rd page"])

*See the full example* "here"

======================================================================

The documentation snippet, the above (Example 3) code was rendered
from:

*Filename: example.rst*

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

   .. container:: jsphinx-download

       .. literalinclude:: examples/simple/snippet_3.py
           :language: python
           :lines: 4-5

       *See the full example*
       :download:`here <examples/simple/snippet_3.py>`

======================================================================


Example 4
---------

In order to customise the blocks "DOCX" file is built from, the
"StringTemplate" class is used. See the example below for usage
examples:

   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)],
   )

*See the full example* "here"

======================================================================

The documentation snippet, the above (Example 4) code was rendered
from:

*Filename: example.rst*

   In order to customise the blocks ``DOCX`` file is built from,
   the ``StringTemplate`` class is used. See the example below for usage
   examples:

   .. container:: jsphinx-download

       .. literalinclude:: examples/simple/snippet_4.py
           :language: python
           :lines: 1-27

       *See the full example*
       :download:`here <examples/simple/snippet_4.py>`

======================================================================


"jsphinx-toggle-emphasis" directive usage
=========================================


Example 5
---------

Generate a TXT file.

   from fake import FAKER

   txt_file = FAKER.txt_file()  # Generate a TXT file

   # Tests
   assert txt_file.data["storage"].exists(txt_file)
   assert len(txt_file.data["content"]) > 0

   # Meta-data is stored inside a ``data`` attribute (``dict``).
   # The following line would produce something like /tmp/tmp/tmph8ot.txt
   print(txt_file.data["filename"])
   # The following line would produce a text generated by Faker, used as
   # the content of the generated file.
   print(txt_file.data["content"])

======================================================================

The documentation snippet, the above (Example 5) code was rendered
from:

*Filename: example.rst*

   Generate a TXT file.

   .. container:: jsphinx-toggle-emphasis

       .. code-block:: python
           :emphasize-lines: 3

           from fake import FAKER

           txt_file = FAKER.txt_file()  # Generate a TXT file

           # Tests
           assert txt_file.data["storage"].exists(txt_file)
           assert len(txt_file.data["content"]) > 0

           # Meta-data is stored inside a ``data`` attribute (``dict``).
           # The following line would produce something like /tmp/tmp/tmph8ot.txt
           print(txt_file.data["filename"])
           # The following line would produce a text generated by Faker, used as
           # the content of the generated file.
           print(txt_file.data["content"])

======================================================================


Example 6
---------

You could increase the file size by passing *nb_chars* parameter.

   from fake import FAKER

   txt_file = FAKER.txt_file(nb_chars=10_000)  # Generate a TXT file

   # Tests
   assert txt_file.data["storage"].exists(txt_file)
   assert len(txt_file.data["content"]) > 0

======================================================================

The documentation snippet, the above (Example 6) code was rendered
from:

*Filename: example.rst*

   .. container:: jsphinx-toggle-emphasis

       .. code-block:: python
           :emphasize-lines: 3

           from fake import FAKER

           txt_file = FAKER.txt_file(nb_chars=10_000)  # Generate a TXT file

           # Tests
           assert txt_file.data["storage"].exists(txt_file)
           assert len(txt_file.data["content"]) > 0

======================================================================


"jsphinx-toggle-emphasis-replace" directive usage
=================================================


Example 7
---------

Generate a TXT file.

   from fake import FAKER

   txt_file = FAKER.txt_file()  # Generate a TXT file

   # Tests
   assert txt_file.data["storage"].exists(txt_file)
   assert len(txt_file.data["content"]) > 0

======================================================================

The documentation snippet, the above (Example 7) code was rendered
from:

*Filename: example.rst*

   Generate a TXT file.

   .. container:: jsphinx-toggle-emphasis-replace

       .. code-block:: python
           :emphasize-lines: 3

           from fake import FAKER

           txt_file = FAKER.txt_file()  # Generate a TXT file

           # Tests
           assert txt_file.data["storage"].exists(txt_file)
           assert len(txt_file.data["content"]) > 0

======================================================================


Example 8
---------

You could increase the file size by passing *nb_chars* parameter.

   from fake import FAKER

   txt_file = FAKER.txt_file(nb_chars=10_000)  # Generate a TXT file

   # Tests
   assert txt_file.data["storage"].exists(txt_file)
   assert len(txt_file.data["content"]) > 0

======================================================================

The documentation snippet, the above (Example 8) code was rendered
from:

*Filename: example.rst*

   You could increase the file size by passing `nb_chars` parameter.

   .. container:: jsphinx-toggle-emphasis-replace

       .. code-block:: python
           :emphasize-lines: 3

           from fake import FAKER

           txt_file = FAKER.txt_file(nb_chars=10_000)  # Generate a TXT file

           # Tests
           assert txt_file.data["storage"].exists(txt_file)
           assert len(txt_file.data["content"]) > 0


"jsphinx-download-replace" directive usage
==========================================


Example 9
---------

See the following full functional snippet for generating a "DOCX"
file.

   # Required imports
   from fake import FAKER

   # Generate DOCX file
   docx_file = FAKER.docx_file()

*Toggle the full example* "here"

======================================================================

The documentation snippet, the above (Example 9) code was rendered
from:

*Filename: example.rst*

   See the following full functional snippet for generating a ``DOCX`` file.

   .. container:: jsphinx-download-replace

       .. literalinclude:: examples/simple/snippet_1.py
           :language: python
           :lines: 1-5

       *Toggle the full example*
       :download:`here <examples/simple/snippet_1.py>`

======================================================================


Example 10
----------

See the example below for "nb_pages" tweak:

   # Generate DOCX file of 100 pages
   docx_file = FAKER.docx_file(nb_pages=100)

*Toggle the full example* "here"

======================================================================

The documentation snippet, the above (Example 10) code was rendered
from:

*Filename: example.rst*

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

   .. container:: jsphinx-download-replace

       .. literalinclude:: examples/simple/snippet_2.py
           :language: python
           :lines: 4-5

       *Toggle the full example*
       :download:`here <examples/simple/snippet_2.py>`

======================================================================