Improve documentation

Signed-off-by: Pedro Algarvio <palgarvio@vmware.com>

.pylint-spelling-words

@@ -18,6 +18,7 @@ basepath
 baz
 bool
 booleans
+caplog
 changelog
 cli
 cli's
@@ -81,6 +82,7 @@ ips
 iterable
 json
 kwargs
+levelname
 linenum
 linux
 localhost

changelog/92.improvement.rst

@@ -0,0 +1 @@
+Improve documentation

docs/conf.py

@@ -160,7 +160,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "pytest": ("https://docs.pytest.org/en/stable/", None),
-    "salt": ("https://docs.saltproject.io/en/latest", None),
+    "salt": ("https://docs.saltproject.io/en/latest/", None),
     "psutil": ("https://psutil.readthedocs.io/en/latest/", None),
     "coverage": ("https://coverage.readthedocs.io/en/latest/", None),
     "pytestshellutils": ("https://pytest-shell-utilities.readthedocs.io/en/latest/", None),

docs/ref/saltfactories/plugins/log_server.rst

@@ -2,7 +2,3 @@ Log Server
 ==========
 
 .. automodule:: saltfactories.plugins.log_server
-   :members:
-   :show-inheritance:
-   :inherited-members:
-   :no-undoc-members:

docs/ref/saltfactories/plugins/sysinfo.rst

@@ -2,7 +2,3 @@ System Information
 ==================
 
 .. automodule:: saltfactories.plugins.sysinfo
-   :members:
-   :show-inheritance:
-   :inherited-members:
-   :no-undoc-members:

docs/topics/fixtures.rst

@@ -16,5 +16,5 @@ Fixtures
 
 The fixture **must** return a dictionary, where the keys are the salt modules that need to be patched, and the values
 are dictionaries. These dictionaries should have the
-:py:data:`salt dunders <salt:dunder-dictionaries>` as keys. These dunders are dictionaries that the
+:ref:`salt dunders <salt:dunder-dictionaries>` as keys. These dunders are dictionaries that the
 salt loader injects at runtime, so, they are not available outside of Salt's runtime.

src/saltfactories/plugins/log_server.py

@@ -1,5 +1,27 @@
 """
-Salt Factories Log Server.
+The Salt Factories Log Server is responsible to receive log records from the salt daemons.
+
+Because all of Salt's daemons and CLI tools are started in subprocesses, there's really no easy way to get those logs
+into the main process where the test suite is running.
+
+However, salt is extensible by nature, and it provides a way to attach custom log handlers into python's logging
+machinery.
+
+We take advantage of that and add a custom logging handler into subprocesses we start for salt. That logging handler
+will then forward **all** log records into this log server, which in turn, injects them into the logging machinery
+running in the test suite.
+
+This allows one to use PyTest's :fixture:`caplog fixture <pytest:caplog>` to assert against log messages.
+
+As an example:
+
+.. code-block:: python
+
+    def test_baz(caplog):
+        func_under_test()
+        for record in caplog.records:
+            assert record.levelname != "CRITICAL"
+        assert "wally" not in caplog.text
 """
 import logging
 import threading

src/saltfactories/plugins/sysinfo.py

@@ -1,9 +1,89 @@
+# pylint: disable=wrong-spelling-in-docstring
 """
-Salt Factories System Information Plugin.
+The system information plugin can be enabled by passing ``--sys-info`` to pytest.
+
+When enabled it will include some output sections when starting pytest.
+Here's an example of the output(partial, for brevity):
+
+.. code-block:: console
+
+   >>>>>>>>>>>>>>>>>>>>>>>>>>> System Information >>>>>>>>>>>>>>>>>>>>>>>>>>>
+   -------------------------- Salt Versions Report --------------------------
+     Salt Version:
+               Salt: 3003
+
+     Dependency Versions:
+               cffi: Not Installed
+           cherrypy: Not Installed
+           dateutil: Not Installed
+          docker-py: 5.0.0
+              gitdb: Not Installed
+          gitpython: Not Installed
+             Jinja2: 3.0.1
+            libgit2: Not Installed
+           M2Crypto: Not Installed
+               Mako: Not Installed
+            msgpack: 1.0.2
+       msgpack-pure: Not Installed
+       mysql-python: Not Installed
+          pycparser: Not Installed
+           pycrypto: Not Installed
+       pycryptodome: 3.10.1
+             pygit2: Not Installed
+             Python: 3.7.7 (default, Oct 24 2021, 07:30:53)
+       python-gnupg: Not Installed
+             PyYAML: 5.4.1
+              PyZMQ: 22.1.0
+              smmap: Not Installed
+            timelib: Not Installed
+            Tornado: 4.5.3
+                ZMQ: 4.3.4
+
+     System Versions:
+               dist: arch rolling n/a
+             locale: UTF-8
+            machine: x86_64
+            release: 5.16.2-arch1-1
+             system: Linux
+            version: Arch Linux rolling n/a
+   -------------------------- System Grains Report --------------------------
+     biosreleasedate: 12/06/2019
+     biosversion: N1EET87W (1.60 )
+     cpu_flags:
+     - fpu
+     - vme
+     gpus:
+      - model: HD Graphics 530
+        vendor: intel
+      - model: GM107GLM [Quadro M1000M]
+        vendor: nvidia
+     kernelrelease: 5.16.2-arch1-1
+     kernelversion: '#1 SMP PREEMPT Thu, 20 Jan 2022 16:18:29 +0000'
+     locale_info:
+       defaultencoding: UTF-8
+       defaultlanguage: pt_PT
+       detectedencoding: UTF-8
+       timezone: unknown
+     mem_total: 64137
+     num_cpus: 8
+     num_gpus: 2
+     os: Arch
+     os_family: Arch
+     osarch: x86_64
+     oscodename: n/a
+     osfinger: Arch-rolling
+     osfullname: Arch
+     osrelease: rolling
+     virtual: physical
+     zfs_feature_flags: false
+     zfs_support: false
+     zmqversion: 4.3.4
+   <<<<<<<<<<<<<<<<<<<<<<<<<<< System Information <<<<<<<<<<<<<<<<<<<<<<<<<<<
 
 ..
     PYTEST_DONT_REWRITE
 """
+# pylint: enable=wrong-spelling-in-docstring
 import io
 import pathlib
 import tempfile