Merge remote-tracking branch 'ldoktor/docs'

Signed-off-by: NCleber Rosa <crosa@redhat.com>

docs/source/Configuration.rst

@@ -124,7 +124,7 @@ When running tests, we are frequently looking to:
   images
 
 Avocado has a module dedicated to find those paths, to avoid cumbersome
-path manipulation magic that people had to do in previous test frameworks [1].
+path manipulation magic that people had to do in previous test frameworks [#f1]_.
 
 If you want to list all relevant directories for your test, you can use
 `avocado config --datadir` command to list those directories. Executing
@@ -163,4 +163,4 @@ since that is customary among unix programs.
 The next section of the documentation explains how you can see and set config
 values that modify the behavior for the Avocado utilities and plugins.
 
-[1] For example, autotest.
+.. [#f1] For example, autotest.

docs/source/DevelopmentTips.rst

@@ -55,17 +55,11 @@ Remote debug with Eclipse
 =========================
 
 Eclipse is a nice debugging frontend which allows remote debugging. It's very
-simple. The only thing you need is Eclipse with pydev plugin. Then you
-need to locate the pydevd path (usually
-`$INSTALL_LOCATION/plugins/org.python.pydev_*/pysrc` or
-`~/.eclipse/plugins/org.python.pydev_*/pysrc`. Then you set the breakpoint by::
+simple. The only thing you need is Eclipse with pydev plugin. The simplest
+way is to use ``pip install pydevd`` and then you set the breakpoint by::
 
-    import sys
-    sys.path.append("$PYDEV_PATH")
     import pydevd
-    pydevd.settrace("$IP_ADDR_OF_ECLIPSE_MACHINE")
-
-Alternatively you can export PYTHONPATH=$PYDEV_PATH and use only last 2 lines.
+    pydevd.settrace(host="$IP_ADDR_OF_ECLIPSE_MACHINE", stdoutToServer=False, stderrToServer=False, port=5678, suspend=True, trace_only_current_thread=False, overwrite_prev_trace=False, patch_multiprocessing=False)
 
 Before you run the code, you need to start the Eclipse's debug server. Switch
 to `Debug` perspective (you might need to open it first

docs/source/Loaders.rst

@@ -52,6 +52,26 @@ as some of them result in error)::
         > EXTERNAL     this_does_not_exist
         > SIMPLE       /bin/echo
 
+Running simple tests with arguments
+===================================
+
+This used to be supported out of the box by running
+``avocado run "test arg1 arg2"`` but it was quite confusing and removed.
+It is still possible to achieve that by using shell and one can even combine
+normal tests and the parametrized ones::
+
+    $ avocado run --loaders file external:/bin/sh -- existing_file.py "'/bin/echo something'" nonexisting-file
+
+This will run 3 tests, the first one is a normal test defined by
+``existing_file.py`` (most probably an instrumented test). Then
+we have ``/bin/echo`` which is going to be executed via
+``/bin/sh -c '/bin/echo something'``. The last one would be
+``nonexisting-file`` which would execute ``/bin/sh -c nonexisting-file``
+which most probably fails.
+
+Note that you are responsible for quotating the test-id (see the
+``"'/bin/echo something'"`` example).
+
 Filtering tests by tags
 =======================
 

docs/source/WritingTests.rst

@@ -56,15 +56,18 @@ 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 Multiplexer, about which
   you can find that more information at :doc:`Mux`.
+* And many more (see :mod:`avocado.core.test.Test`)
 
 Saving test generated (custom) data
 ===================================
 
 Each test instance provides a so called ``whiteboard``. It can be accessed
 through ``self.whiteboard``. This whiteboard is simply a string that will be
-automatically saved to test results (as long as the output format supports it).
-If you choose to save binary data to the whiteboard, it's your responsibility to
-encode it first (base64 is the obvious choice).
+automatically saved to test results after the test finishes (it's not synced
+during the execution so when the machine or python crashes badly it might
+not be present and one should use direct io to the ``outputdir`` for
+critical data). If you choose to save binary data to the whiteboard,
+it's your responsibility to encode it first (base64 is the obvious choice).
 
 Building on the previously demonstrated ``sleeptest``, suppose that you want to save the
 sleep length to be used by some other script or data analysis tool::
@@ -376,6 +379,8 @@ It can be run by::
 
    OK
 
+But we'd still recommend using ``avocado.main`` instead which is our main entry point.
+
 Setup and cleanup methods
 =========================
 
@@ -747,14 +752,6 @@ namely the ``--output-check-record`` argument with values ``stdout``,
 to the files ``stdout.expected`` and ``stderr.expected`` at the test's
 data directory (which is different from the job/test results directory).
 
-Avocado Tests run on a separate process
-=======================================
-
-In order to avoid tests to mess around the environment used by the main
-Avocado runner process, tests are run on a forked subprocess. This allows
-for more robustness (tests are not easily able to mess/break Avocado) and
-some nifty features, such as setting test timeouts.
-
 Setting a Test Timeout
 ======================
 
@@ -879,7 +876,7 @@ Another way to skip tests is by using the Avocado skip decorators:
   ``False``
 
 Those decorators can be used with both ``setUp()`` method and/or and in the
-test methods. The test below::
+``test*()`` methods. The test below::
 
     import avocado
 
@@ -941,7 +938,8 @@ If your test is a method in a class that directly inherits from
 Now, the need may arise for more complex tests, to use more advanced
 Python features such as inheritance.  For those tests that are written
 in a class not directly inherting from :class:`avocado.Test`, Avocado
-may need your help.
+may need your help, because Avocado uses only static analysis to examine
+the files.
 
 For example, suppose that you define a new test class that inherits
 from the Avocado base test class, that is, :class:`avocado.Test`, and
@@ -1303,7 +1301,7 @@ Here are the current variables that Avocado exports to the tests:
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 | AVOCADO_TEST_SYSINFODIR     | The system information directory      | $HOME/logs/job-results/job-2014-09-16T14.38-ac332e6/test-results/$HOME/my_test.sh.1/sysinfo         |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
-| *                           | All variables from --mux-yaml         | TIMEOUT=60; IO_WORKERS=10; VM_BYTES=512M; ...                                                       |
+| `***`                       | All variables from --mux-yaml         | TIMEOUT=60; IO_WORKERS=10; VM_BYTES=512M; ...                                                       |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+