After reading the text and shuffling the order a bit, I think this
has an easier to follow structure. A few highlights:

* An Avocado test is really a method, that is, for many methods we
  have many tests.
* Suppress the attempt to briefly explain the Multiplexer here,
  giving instead a link to a more complete documentation.

Changes from v1:
* Mention the function naming conventions for the test methods and
  link to PEP 8 relevant section for functions and classes.
* Break into finer grained sections.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

[fixup] docs: simplify Writing Avocado Test section text
Signed-off-by: NCleber Rosa <crosa@redhat.com>

The idea is to remove everything that is not critical to the user's
understanding of the core concepts.

Also, to sync to the new multi-test in a single class capabilities
of Avocado, let's name the main test method `test`. This paves the
way for other (multi test) examples that name test methods with
the exact same prefix (test_foo, test_bar and so on).
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This includes moving the reference text and diagram on test order
resolution to the Reference Guide. Since this also included
information on what are simple and instrumented tests, let's
merge and reuse that.

Also, let's rename "Simple example" to "Basic example" so that it
does not confuse users with the concept of a Simple Test, since this
example is actually an Instrumented Test.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This commit tries to reduce the learning curve for a new Avocado user.

* The sections were broken down with new levels
* Reduce text by using links if users want more information on a topic
* Introduced a Reference Guide, where these more detailed and often
  design/internals about Avocado will be documented.
* Default the usage examples assuming an installation based on packages
* A lot of wording changes, always intending to make it simpler

Changes from v1:
* Wording changes suggested by Lucas.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

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

First, let's assume these docs are intended for users by renaming
the first section simply "Installing Avocado".

I tried to make the "Installing Avocado" introductory text shorter,
so that it's easier to read, and if the user really wants to take
a look at the repos he/she can click on the links.

Also broke down the installation section into more sub levels.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This makes it even more clear that this feature is about a command
line option and can work with unmodified tests.

Also, the user reading this will at least know that some other
options are available, and will probably refer back to `--help`
if he needs further assistance.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Two sentences in the usage string of the --gdb-pre-run-commands
command line option lacked a white space between them, making it
difficult on the user to quickly read it and grasp it.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Since the command line (aka transparent execution of binaries) use
case is easier to grasp and probably will see more frequent use then
the API, let's present that first.

Also, standardize on the feature names, fix some typos and add a
little bit more of cross reference.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Like a git commit message, let's try to be really succient about the
first line a user will read about avocado.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Since Avocado in our context is a proper name, and not really just
some fruit, let's refer to it using a capitalized word.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Sure, sphix gave us a hand with the generation of the index file to
point us to the right direction. But, by now, we don't have to keep
that old tip.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

For completeness purporses this adds the current year to the copyright
string.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

As it was done in the man pages a while ago, it's probably better to
just refer to the Avocado Team as the author of the documentation as a
whole.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

API Review (2nd round) - Reviewed Bits - v3

And while doing that, also remove avocado.linux for good, since no one else
lives there.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

And while doing that, also change the import style on sysinfo.py so that it
matches the most common style in our tree, that is, individual utility modules
instead of the whole utils module.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Since this class is defined on the same module, let's use a relative
reference to it.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This exception is only raised by avocado.utils.process itself (and by
avocado.utils.remote which mimics the the first). Also, since avocado.utils
should not use anything from avocado.core, it should be moved anyway.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This is a utility module with no dependency on any other Avocado
module, so a good candidate for the utils namespace.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Only avocado.Test is of general interest to test writers. For that reason
the entire test module has been moved to the avocado.core namespace.

The recommended way to go about writing instrumented tests is something like:

   from avocado import Test
   class MyTest(Test):
      def test_foo(self):
         do_stuff()

Changes from v2:
* Fixed references in docstrings
* Fixed refrences of avocado.test in Writing Test Guide docs

Changes from v1:
* Fixed comment typo on commit message
* Fixed old reference of avocado.test (then test.Test) instead of
  avocado then Test in GDB docs.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

This way we work similarly as to when we develop
avocado-virt, which is in fact very convenient.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Some upcoming test sources may want to simply append
multiplexer params to their original params, instead
of having them overwritten by avocado. Let's Define a
mechanism to do that. Test sources, as they assemble
the params that will be used with the test classes, may
define the key avocado_inject_params and set it to True.

If the avocado finds out about that param, it will append
the avocado specific params in the param 'avocado_params',
making it possible for said upcoming test classes to
retrieve avocado specific params.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

The last refactor allowed us to move loader specific info to test
loader plugins. This will allow new test loader plugins to add
new information about how to classify/find new tests, in a way
that we can list new tests without having to modify the test
lister plugin.

We did modify the test lister to list the extra test sources,
and also made it a priority 0 plugin, to ensure extra test
sources plugins get loaded after it, effectively preventing
errors like:

AttributeError: 'Namespace' object has no attribute 'vt_list_guests'
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

Allow multiple plugins to implement a TestLoader class
that will allow avocado to understand new types of tests.
The url list will be passed through available test loaders,
that will see if they can handle it, if they can't, they pass
to the next one until we find out one loader that can take
care of the job.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

avocado.multiplexer: Evaluate abspath from right

One of the requirements is to evaluate paths from right to left. This
works fine with relative paths, but was intentionally disabled for
absolute paths. Anyway this behavior is wrong and both, absolute and
relative, paths should be evaluated from right to left and allow
remaining path on left.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

trinity example test: fix fetch of tarball parameter and update to 1.5

Because of the parameter behaviour change this test was failing to get
the name of the tarball to use during the test.

Once that was fixed, there was a couple of build errors. Instead of
debugging the build of the 1.4 version, I tried version 1.5, which
built without any problems. Let's use this oppotunity to fix the
test (wrapper) and update the (original test) tarball.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

avocado.multiplexer: Support for modifying multiplex tree on cmdline [v3]

This patch adds "--env" argument, which allows one to specify
[path:]key:value records which are injected into the multiplex tree
parsed from yaml files.

It also demonstrate the way plugins can override multiplex tree
therefor modify test params during activate/run phase.

There are few intrusive changes. It reuses the existing namespace
during "avocado.core.parser.Parser.finish" part to keep the values set
during "Plugin.activate" phase and it adds
"self.args.default_multiplex_tree" argument which is reserved for
multiplex tree to be merged into tree made from yaml files.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

This function can be used to retrieve existing node by path separated
by '/'. Additionally when "create" is supplied it it can create the
missing nodes in the same way as "mkdir -p" in bash.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

Originally we used multiplex = True and False. This patch adds None and
the value is not updated during merge when the new node's multiplex is
None.

Currently this means that once node is set as multiplex, there is no way
to undo this. We might consider creating !nomux flag in the future to
force multiplex = False, but this is currently not needed.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

The TreeNodeDebug needs the origin to work properly. This patch allows
combyining debug and non-debug trees by supplying "Unknown" origin when
to non-debug TreeNodes.
Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

Signed-off-by: NLukáš Doktor <ldoktor@redhat.com>

avocado.multiplexer: Inject YAML files into /run [v2]

To simplify further changes in the test lister, to accomodate listing
tests from different plugins into the same command.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

This test exception was lost, even though we use it in
the definition of the avocado.test.MissingTest class.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>

We need the flexibility to implement plugins that need to
display setup operations.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>