Documente how to use ramfs for faster I/O = faster test (#252)

Contributors:
  * @spirillen 

* Knowen Issue Cygwin

Have made some notes about the limitation of running Cygwin or Python on a Windows and how it is affecting @PyFunceble

Signed by @spirillen

* Added Power(less)shell to the title for know Windows issues...

Signed by @spirillen

* Major changes to docs/

With this release I have made some minor textual changes, but big changes to the filestructure as I have renamed the files inside docs/usage/. This is done to make the filename + the titles more systematic and equal, it just leaves the "mess" it used to be.

Signed by @spirillen

* Tiny fixup of the text for .PyFunceble.yaml

Ensuring that no misunderstands the .PyFunceble.yaml is overwritten by default since .PyFunceble.overwrite.yaml was introduced.

* Updated example IP's to RFC:5737

Signed by @spirillen

* Ordering the Usage docs

Fixed a small Wording

Refs: #247 (comment)

Signed by @spirillen

* Experimental filenaming for deprecated args

Relates to #247 (comment)

fix #247 (comment)

Signed by @spirillen

* Rename bash-terminal.rst to terminal.rst

Fixes #247 (comment)

* Update index.rst in docs

Forgot to update the docs/usage/idex.rst to meet the new filename of terminal.rst.

* Small rewrite of the intro in terminal.rst

And a few missing duble lines between arguments

Previous commit within same PR tuched https://mypdns.org/spirillen/PyFunceble/-/issues/26

* Wrote in depth about .PyFunceble.overwrite.yaml

I also spotted a few lines, which was pushing the 72 chars per line boundries.

(72 vs 80 chars per line, for support of Unix consoles)

This commit tuches #246 to better desription of the .PyFunceble.overwrite.yaml as requested by @ZeroDot1

* Fixing a BUG in the code example

By a mistake there was written `-url "$URI"` which of curse should have been `-u "$URI"`. The mistake was spotted in easylist/easylist#9061 (comment) posted by @ryanbr

* Written about how to speedup test with ramFS

Solved a few github link issues to @spirillen's profile

* Improvement of ramFS text

Have fixed markup of code-block
fixed markup of the indented paragraph and changed it to a info block, as it seems more right
Fixed the Url's

* Trying to fix typo and grammar.

Co-authored-by: Nissar Chababy <[email protected]>
Co-authored-by: Spirillen Marsupilami <[email protected]>

Author: spirillen

docs/facts/faq.rst

@@ -5,15 +5,17 @@ How to speed up the test process?
 ---------------------------------
 
 .. warning::
-    Beware, when talking about speed a lot a thing have to be taken in consideration.
-    Indeed here is a non exhaustive list of things which fluctuate testing speed.
+    Beware, when talking about speed a lot of things have to be taken into consideration.
+    Indeed here is a non-exhaustive list of things that fluctuate the testing speed.
 
     * Bandwidth.
     * DNS Server response time.
     * CPU.
-    * ISP blocking a big amount of connection to the outside world.
+    * ISP's who blocks a big amount of connection to the outside world.
     * Our databases management (do not apply for MySQL and MariaDB format).
     * Amount of data to test.
+    * Disk I/O in particular as PyFunceble is heavy on the I/O
+      * RamDrives and NVME disks are very suitable for PyFunceble CSV db.
     * ...
 
 I have a dedicated server or machine just for PyFunceble
@@ -22,21 +24,97 @@ I have a dedicated server or machine just for PyFunceble
 Simply increase the number of maximal workers PyFunceble is allowed to use
 through the `--max-workers <../usage/index.html#w-max-workers>`_ argument.
 
-By default the number of workers is equal to:
+By default, the number of workers is equal to:
 
 ::
 
     CPU CORES - 2
 
-meaning that if you have 8 CPU cores, the value will be automatically set to
-:code:`6`.
+meaning that if you have :code:`8` CPU threads, the value will be
+automatically set to :code:`6`.
 
 
 .. warning::
-    Keep in mind that the :code:`--max-workers` mostly - if not only - affects
-    the tester processes. Because we want to safely write the files, we still
-    need a single processes which read the submitted results and generate the
-    outputs.
+    Keep in mind that the :code:`--max-workers` (:code:`-w`) mostly - if
+    not only - affects the tester processes. Because we want to safely
+    write the files(Disk I/O), we still need a single process that reads the
+    submitted results and generates the outputs.
 
-    The reason we added this to PyFunceble :code:`4.0.0` is we don't want to
-    have a wrongly formatted output file.
+    The reason we added this to PyFunceble :code:`4.0.0` is we don't want
+    to have a wrongly formatted file output.
+
+
+Setup and use ramfs
+-------------------
+What is a ramfs and why not use tmpfs?
+
+:code:`ramfs` is better than :code:`tmpfs` when data needs to be secret,
+since :code:`ramfs` data never gets swapped (saved to a physical storage
+drive), while tmpfs may get swapped.
+Third parties who later gain root or physical access to the machine then
+can inspect the swap space and extract sensitive data.
+
+The HOWTO solution
+^^^^^^^^^^^^^^^^^^
+You can prepare :code:`ramfs` mount so any non-privileged user can
+mount/unmount it on-demand.
+
+To do this, you will need root privilege, once. Ask the administrator of
+your system to set this up for you, if you lack root privileges.
+
+At first, you need to add a line to the :code:`/etc/fstab`. The line in
+fstab may look like this:
+
+
+.. :code-block:: console
+    none    /mnt/ramfs    ramfs    noauto,user,size=1024M,mode=0777    0    0
+
+* :code:`/mnt/ramfs` is a mount point, where the ramfs filesystem will be
+  mounted. Directory **most** exist.
+* :code:`noauto` option prevents this from being mounted automatically
+  (e.g. at system's boot-up).
+* :code:`user` makes this mountable by regular users.
+* :code:`size` sets this "ramdisk's" size (you can use :code:`M` and
+  :code:`G` here)
+* :code:`mode` is very important, with the octal :code 0770 only root and
+  user, who mounted this filesystem, will be able to read and write to
+  it, not the others (you may use different :code of your choice as well,
+  but be very sure about it!).
+
+.. note::
+
+    We recommend you to set the file mode to :code:`0777` in case you
+    are using this in relation to any kind of scripting, to ensure
+    subprocesses have access to the file(s). In all other cases, you should set the folder
+    permision to :code:`0770`.
+
+**Mount**
+
+  .. code-block:: console
+
+      $ mount /mnt/ramfs/
+
+
+**Unmount**
+
+  .. code-block:: console
+
+      $ umount /mnt/ramfs/
+
+
+This chapter has practically been copied from
+`<https://unix.stackexchange.com/a/325421>`_ creditted to Neurotransmitter
+as it is well written and cover our purpose for describing how to setup a
+ramFS to be used for testing with PyFunceble.
+
+Next, we need to configure PyFunceble to use the newly created and mounted
+ramFS. This is done with the 
+`PYFUNCEBLE_OUTPUT_LOCATION <../usage/index.html#global-variables>`_ ; now
+all outputs are stored in the ramFS, so remember to copy the results to a
+stationary file path when you are done.
+
+Next time you are going to run a test with PyFunceble are will do:
+  1. Mount the ramFS
+  2. Copy the last test results to the ramFS
+  3. Run your test
+  4. Copy your results from ramFS to a stationary file path.

docs/special-thanks.rst

@@ -75,8 +75,8 @@ which helped and/or still help me build, test and or make `PyFunceble`_ a better
 .. _@rthalley: https://github.com/rthalley
 .. _@ScriptTiger: https://github.com/ScriptTiger
 .. _@SMed79: https://github.com/SMed79
-.. _@spirillen: https://github.com/spirillen
+.. _@spirillen: https://mypdns.org/spirillen
 .. _@tartley: https://github.com/tartley
 .. _@theskumar: https://github.com/theskumar
 .. _@yaml: https://github.com/yaml
-.. _@ybreza: https://github.com/ybreza
+.. _@ybreza: https://github.com/ybreza

docs/usage/terminal.rst

@@ -1072,7 +1072,7 @@ CPU - 2. Otherwise, it will 1.
     - **This means you should be experimenting a bit your self.**
 
     To follow the "behind the scene" talk about the subject, please take a
-    look at `issue <https://github.com/spirillen/PyFunceble/issues/34>`_
+    look at `issue <https://mypdns.org/spirillen/PyFunceble/-/issues/34>`_
 
 
 ------