Add create files to docs (#222)

CHANGELOG.rst

@@ -16,6 +16,14 @@ are used for versioning (schema follows below):
   0.3.4 to 0.4).
 - All backwards incompatible changes are mentioned in this document.
 
+0.10.5
+------
+*Unreleased*
+
+- Add benchmarks section to the main README.
+- Improve docs. Add a dedicated section on files creation.
+- Minor clean-up.
+
 0.10.4
 ------
 2024-10-17

README.rst

@@ -24,6 +24,7 @@ fake.py
 .. _Recipes: https://fakepy.readthedocs.io/en/latest/recipes.html
 .. _Factories: https://fakepy.readthedocs.io/en/latest/factories.html
 .. _Customization: https://fakepy.readthedocs.io/en/latest/customization.html
+.. _Creating files: https://fakepy.readthedocs.io/en/latest/creating_files.html
 .. _Creating PDF: https://fakepy.readthedocs.io/en/latest/creating_pdf.html
 .. _Creating DOCX: https://fakepy.readthedocs.io/en/latest/creating_docx.html
 .. _Creating ODT: https://fakepy.readthedocs.io/en/latest/creating_odt.html
@@ -121,6 +122,7 @@ Documentation
 - For various ready to use code examples see the `Recipes`_.
 - For tips on how to use the factories see the `Factories`_.
 - For customization tips see the `Customization`_.
+- For generic information on how to create files see `Creating files`_.
 - For tips on ``PDF`` creation see `Creating PDF`_.
 - For tips on ``DOCX`` creation see `Creating DOCX`_.
 - For tips on ``ODT`` creation see `Creating ODT`_.

docs/_static/examples/creating_pdf/text_pdf_bytes_2b.py

@@ -0,0 +1,4 @@
+from fake import FAKER, TextPdfGenerator
+
+texts = ["Page 1 content", "Page 2 content", "Page 3 content"]
+pdf_bytes = FAKER.pdf(texts=texts, generator=TextPdfGenerator)

docs/creating_files.rst

@@ -0,0 +1,94 @@
+Creating files
+==============
+
+.. Internal references
+
+.. _fake.py: https://github.com/barseghyanartur/fake.py/
+.. _Creating archives: https://fakepy.readthedocs.io/en/latest/creating_archives.html
+.. _Creating DOCX: https://fakepy.readthedocs.io/en/latest/creating_docx.html
+.. _Creating images: https://fakepy.readthedocs.io/en/latest/creating_images.html
+.. _Creating ODT: https://fakepy.readthedocs.io/en/latest/creating_odt.html
+.. _Creating PDF: https://fakepy.readthedocs.io/en/latest/creating_pdf.html
+
+Creation of specific file formats is extensively covered in dedicated
+sections:
+
+- `Creating archives`_
+- `Creating DOCX`_
+- `Creating images`_
+- `Creating ODT`_
+- `Creating PDF`_
+
+This section covers basic concepts of file generation within `fake.py`_.
+
+It's possible to generate either bytes or files on the file system.
+
+- When generating bytes, the returned value is ``BytesValue``.
+
+- When generating files on the file system, the returned value
+  is ``StringValue``.
+
+Both ``BytesValue`` and ``StringValue`` behave like ``bytes`` and ``str``
+respectively, but have a ``data`` (``dict``) property, which contains useful
+meta-data about the specific kind of file.
+
+For generated files, it will always have the following:
+
+- ``storage``: Storage class that was used to generate the file.
+- ``filename``: Absolute file path. It's important to know, that string
+  representation of the file contains a relative file path.
+
+----
+
+See the example below for a graphic PDF generation:
+
+.. container:: jsphinx-toggle-emphasis
+
+    .. code-block:: python
+        :name: test_pdf_file
+        :emphasize-lines: 3
+
+        from fake import FAKER
+
+        pdf_file = FAKER.pdf_file()
+
+        print(pdf_file)
+        # tmp/tmpnvwoa2ap.pdf
+
+        print(pdf_file.data["filename"])
+        # /tmp/tmp/tmpnvwoa2ap.pdf
+
+        print(pdf_file.data)
+        # {'storage': <fake.FileSystemStorage at 0x7f72221fd750>,
+        #  'filename': '/tmp/tmp/tmpragc8wyr.pdf',
+        #  'content': None}
+
+----
+
+See the example below for a text PDF generation:
+
+.. container:: jsphinx-toggle-emphasis
+
+    .. code-block:: python
+        :name: test_text_pdf_file
+        :emphasize-lines: 3
+
+        from fake import FAKER
+
+        pdf_file = FAKER.text_pdf_file()
+
+        print(pdf_file)
+        # tmp/tmpragc8wyr.pdf
+
+        print(pdf_file.data["filename"])
+        # /tmp/tmp/tmpragc8wyr.pdf
+
+        print(pdf_file.data)
+        # {'storage': <fake.FileSystemStorage at 0x7f7222157750>,
+        #  'filename': '/tmp/tmp/tmpragc8wyr.pdf',
+        #  'content': 'If dutch beats although complex.'}
+
+Note, that text PDF does contain full text of the entire document in the
+``content`` key.
+
+----

docs/creating_pdf.rst

@@ -52,6 +52,25 @@ See the example below for ``texts`` tweak:
 
 ----
 
+For full clarity, see another example below for ``texts`` tweak:
+
+.. container:: jsphinx-download
+
+    .. literalinclude:: _static/examples/creating_pdf/text_pdf_bytes_2b.py
+        :language: python
+        :lines: 3-
+
+    *See the full example*
+    :download:`here <_static/examples/creating_pdf/text_pdf_bytes_2b.py>`
+
+The produced PDF will consist of 3 pages:
+
+- Content of the first would be: ``Page 1 content``
+- Content of the second page would be: ``Page 1 content``
+- Content of the third page would be: ``Page 3 content``
+
+----
+
 See the example below for ``nb_pages`` tweak:
 
 .. container:: jsphinx-download