Examples
========

.. References

.. _fake.py: https://fakepy.readthedocs.io

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.

.. 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>`

----

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

*Filename: example.rst*

.. code-block:: 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:

.. 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>`

----

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

*Filename: example.rst*

.. code-block:: 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:

.. 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>`

----

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

*Filename: example.rst*

.. code-block:: 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:

.. 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>`

----

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

*Filename: example.rst*

.. code-block:: 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.

.. 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"])

----

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

*Filename: example.rst*

.. code-block:: 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.

.. 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

----

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

*Filename: example.rst*

.. code-block:: 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.

.. 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

----

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

*Filename: example.rst*

.. code-block:: 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.

.. 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

----

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

*Filename: example.rst*

.. code-block:: 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.

.. 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>`

----

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

*Filename: example.rst*

.. code-block:: 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:

.. 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>`

----

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

*Filename: example.rst*

.. code-block:: 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>`

----