Doc fixes before LTS - Avocado Writers’s Guide

Updates to documentation in `Avocado Writer’s Guide` section to respects
the latest changes.

Reference: avocado-framework#5757
Signed-off-by: Jan Richter <[email protected]>

docs/source/guides/writer/chapters/libs.rst

@@ -17,7 +17,7 @@ What this means is that upon updating to later minor versions of Avocado, you
 should look at the Avocado Release Notes for changes that may impact your
 tests.
 
-.. seealso:: If you would like a detailed API reference of this libraries,
+.. seealso:: If you would like a detailed API reference of these libraries,
   please visit the "Reference API" section on the left menu.
 
 The following pages are the documentation for some of the Avocado utilities:

docs/source/guides/writer/chapters/logging.rst

@@ -35,7 +35,7 @@ in `log_dir` directory. This file contains all logs which were generated during
 job run. It is very verbose, and it contains even avocado internal logs.
 If the parallel run is enabled (default behavior) the logs are not sorted and
 logs from multiple tests might be mixed together. Therefore, some
-post-processing of this test might be needed for full understanding of these logs. 
+post-processing of this file might be needed for full understanding of these logs.
 The format of logs is::
 
         <date> <time> <namespace> <log level> | <testname>: <log>
@@ -196,6 +196,7 @@ Again you could watch the progress with::
     2023-04-13 17:54:18,916 avocado.job INFO |  'config.datadir': False,
     2023-04-13 17:54:18,916 avocado.job INFO |  'core.paginator': False,
     2023-04-13 17:54:18,916 avocado.job INFO |  'core.show': {'app'},
+    ...
 
 External logs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -234,4 +235,4 @@ You can check the logs by::
         [stdlog] 2023-04-20 10:07:03,998 matplotlib.font_manager DEBUG| findfont: score(FontEntry(fname='/home/janrichter/.pyenv/versions/avocado/lib/python3.10/site-packages/matplotlib/mpl-data/fonts/ttf/STIXGeneralBolIta.ttf', name='STIXGeneral', style='italic', variant='normal', weight=700, stretch='normal', size='scalable')) = 11.335
         [stdlog] 2023-04-20 10:07:03,998 matplotlib.font_manager DEBUG| findfont: score(FontEntry(fname='/home/janrichter/.pyenv/versions/avocado/lib/python3.10/site-packages/matplotlib/mpl-data/fonts/ttf/DejaVuSansMono-Bold.ttf', name='DejaVu Sans Mono', style='normal', variant='normal', weight=700, stretch='normal', size='scalable')) = 10.335
         [stdlog] 2023-04-20 10:07:03,998 matplotlib.font_manager DEBUG| findfont: score(FontEntry(fname='/home/janrichter/.pyenv/versions/avocado/lib/python3.10/site-packages/matplotlib/mpl-data/fonts/ttf/STIXNonUniBol.ttf', name='STIXNonUnicode', style='normal', variant='normal', weight=700, stretch='normal', size='scalable')) = 10.335
-
+        ...

docs/source/guides/writer/chapters/parameters.rst

@@ -11,7 +11,7 @@ Test parameters
 Avocado allows passing parameters to tests, which effectively results in
 several different variants of each test. These parameters are available in
 (test's) ``self.params`` and are of
-:class:`avocado.core.varianter.AvocadoParams` type. You can also access
+:class:`avocado.core.parameters.AvocadoParams` type. You can also access
 these parameters via the configuration dict at `run.test_parameters`
 namespace.
 
@@ -87,12 +87,12 @@ environment represents all the values of the tree.
 AvocadoParams
 ~~~~~~~~~~~~~
 
-:class:`avocado.core.varianter.AvocadoParams`
+:class:`avocado.core.parameters.AvocadoParams`
 
 Is a "database" of params present in every (instrumented) Avocado
 test.  It's produced during :class:`avocado.core.test.Test`'s
 ``__init__`` from a `variant`_. It accepts a list of `TreeNode`_
-objects; test name :class:`avocado.core.test.TestID` (for logging
+objects; test name :class:`avocado.core.test_id.TestID` (for logging
 purposes) and a list of default paths (`Parameter Paths`_).
 
 In test it allows querying for data by using::
@@ -135,10 +135,10 @@ in :ref:`yaml-to-mux-resolution-order` section.
 Variant
 ~~~~~~~
 
-Variant is a set of params produced by `Varianter`_s and passed to the
+Variant is a set of params produced by `Varianter`_ and passed to the
 test by the test runner as ``params`` argument. The simplest variant
 is ``None``, which still produces an empty `AvocadoParams`_. Also, the
-`Variant`_ can also be a ``tuple(list, paths)`` or just the
+Variant can also be a ``tuple(list, paths)`` or just the
 ``list`` of :class:`avocado.core.tree.TreeNode` with the params.
 
 Dumping/Loading Variants
@@ -226,27 +226,6 @@ Example workflow of `avocado run passtest.py -m example.yaml` is::
      |
      + runner._iter_variants -> Varianter.itertests  // Yields variants
 
-In order to allow force-updating the `Varianter`_ it supports
-``ignore_new_data``, which can be used to ignore new data. This is used
-by `Replay` to replace the current run `Varianter`_ with the one
-loaded from the replayed job. The workflow with ``ignore_new_data`` could
-look like this::
-
-   avocado run --replay latest -m example.yaml
-     |
-     + replay.run -> Varianter.is_parsed
-     |
-     + replay.run  // Varianter object is replaced with the replay job's one
-     |             // Varianter.ignore_new_data is set
-     |
-     + job.run_tests -> Varianter.is_parsed
-     |
-     + job._log_variants -> Varianter.to_str
-     |
-     + runner.run_suite -> Varianter.get_number_of_tests
-     |
-     + runner._iter_variants -> Varianter.itertests
-
 The `Varianter`_ itself can only produce an empty variant, but it invokes all 
 `Varianter plugins`_ and if any of them reports variants it yields them 
 instead of the default variant.
@@ -274,7 +253,7 @@ string, and convert it to the appropriate type.
    used with different, or none, varianter plugins, it's safer if
    the test does an explicit check or type conversion.
 
-Because the :class:`avocado.core.varianter.AvocadoParams` mandates the
+Because the :class:`avocado.core.parameters.AvocadoParams` mandates the
 concept of a parameter path (a legacy of the tree based Multiplexer)
 and these test parameters are flat, those test parameters are placed
 in the ``/`` path.  This is to ensure maximum compatibility with tests

docs/source/guides/writer/chapters/writing.rst

@@ -56,11 +56,11 @@ Note that the test class provides you with a number of convenience attributes:
 * A parameter passing system (and fetching system) that can be accessed by
   means of ``self.params``. This is hooked to the Varianter, about which
   you can find that more information at :ref:`test-parameter`.
-* And many more (see `avocado.core.test.Test`)
+* And many more (see :mod:`avocado.core.test.Test`)
 
 To minimize the accidental clashes we define the public ones as properties
 so if you see something like ``AttributeError: can't set attribute`` double
-you are not overriding these.
+check you are not overriding these.
 
 .. _Test statuses:
 
@@ -456,7 +456,7 @@ The code example below uses :meth:`assertEqual
             self.assertTrue(variable)
 
             self.log.debug("Verifying if this test is an instance of test.Test")
-            self.assertIsInstance(self, test.Test)
+            self.assertIsInstance(self, Test)
 
 Running tests under other :mod:`unittest` runners
 -------------------------------------------------
@@ -752,16 +752,16 @@ log.
 You may log something into the test logs using the methods in
 :mod:`avocado.Test.log` class attributes. Consider the example::
 
-    class output_test(Test):
+    class OutputTest(Test):
 
         def test(self):
-            self.log.info('This goes to the log and it is only informational')
-            self.log.warn('Oh, something unexpected, non-critical happened, '
-                          'but we can continue.')
-            self.log.error('Describe the error here and don't forget to raise '
-                           'an exception yourself. Writing to self.log.error '
-                           'won't do that for you.')
-            self.log.debug('Everybody look, I had a good lunch today...')
+            self.log.info("This goes to the log and it is only informational")
+            self.log.warn("Oh, something unexpected, non-critical happened, "
+                          "but we can continue.")
+            self.log.error("Describe the error here and don't forget to raise "
+                           "an exception yourself. Writing to self.log.error "
+                           "won't do that for you.")
+            self.log.debug("Everybody look, I had a good lunch today...")
 
 If you need to write directly to the test stdout and stderr streams,
 Avocado makes two preconfigured loggers available for that purpose,
@@ -770,7 +770,9 @@ Python's standard logging API to write to them. Example::
 
     import logging
 
-    class output_test(Test):
+    from avocado import Test
+
+    class OutputTest(Test):
 
         def test(self):
             stdout = logging.getLogger('avocado.test.stdout')
@@ -784,11 +786,6 @@ into a ``stdout`` file, to be found at the test results directory. The same
 applies to anything a test generates on STDERR, that is, it will be saved
 into a ``stderr`` file at the same location.
 
-Additionally, when using the runner's output recording features,
-namely the ``--output-check-record`` argument with values ``stdout``,
-``stderr`` or ``all``, everything given to those loggers will be saved
-to the files ``stdout.expected`` and ``stderr.expected`` at the test's
-data directory (which is different from the job/test results directory).
 
 Setting a Test Timeout
 ----------------------
@@ -1302,7 +1299,7 @@ tests:
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 | AVOCADO_TEST_BASEDIR        | Base directory of Avocado tests       | $HOME/src/avocado/avocado.dev/examples/tests                                                        |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
-| AVOCADO_TEST_WORKDIR        | Work directory for the test           | /var/tmp/.avocado-taskcx8of8di/test-results/tmp_dirfgqrnbu_/1-Env.test                              |
+| AVOCADO_TEST_WORKDIR        | Work directory for the test           | /var/tmp/.avocado-taskcx8of8di/test-results/tmp_dirfgqrnbu/1-Env.test                              |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 | AVOCADO_TESTS_COMMON_TMPDIR | Temporary directory created by the    | /var/tmp/avocado_cp07qzd9                                                                           |
 |                             | :ref:`plugin_teststmpdir` plugin.  The|                                                                                                     |
@@ -1328,7 +1325,7 @@ tests:
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 | AVOCADO_TEST_BASEDIR        | Base directory of Avocado tests       | $HOME/src/avocado/avocado.dev/examples/tests                                                        |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
-| AVOCADO_TEST_WORKDIR        | Work directory for the test           | /var/tmp/.avocado-taskcx8of8di/test-results/tmp_dirfgqrnbu_/1-Env.test                              |
+| AVOCADO_TEST_WORKDIR        | Work directory for the test           | /var/tmp/.avocado-taskcx8of8di/test-results/tmp_dirfgqrnbu/1-Env.test                              |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 | AVOCADO_TESTS_COMMON_TMPDIR | Temporary directory created by the    | /var/tmp/avocado_XhEdo/                                                                             |
 |                             | :ref:`plugin_teststmpdir` plugin.  The|                                                                                                     |
@@ -1344,8 +1341,6 @@ tests:
 | `***`                       | All variables from --mux-yaml         | TIMEOUT=60; IO_WORKERS=10; VM_BYTES=512M; ...                                                       |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 
-.. note:: The same variables listed for the avocado-instrumented tests above are
-   available to all the test types when using the legacy runner.
 
 SIMPLE Tests BASH extensions
 ----------------------------

docs/source/guides/writer/libs/gdb.rst

@@ -6,12 +6,6 @@ GDB, including setting a executable to be run, setting breakpoints
 or any other types of commands. This requires a test written with
 that approach and API in mind.
 
-.. tip:: Even though this section describes the use of the Avocado GDB
-   features, it's also possible to debug some application offline by
-   using tools such as `rr <http://rr-project.org>`_.  Avocado ships
-   with an example wrapper script (to be used with ``--wrapper``) for
-   that purpose.
-
 APIs
 ----