The reference documentation now contains a section on the libraries and
APIs, giving information on where those can be found in the `avocado`
namespace, and their respective API stability promises.

Then, instead of giving too much information about it in the introductory
section, let's just link to the reference section if the user wants to
know more about it.

Changes from v1:
* Fix typo spotted by Lucas (s/will/you).
Signed-off-by: NCleber Rosa <crosa@redhat.com>

APIs are the interfaces that our libraries provide. So where we actually
want to talk about the full set of value that we provide to test users,
let's use the term libraries. And use APIs when it makes more sense to
do so.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

First, the wording was not clear about the language choices and the
added benefits of using Python. Also, let's focus on using the term
libraries instead of APIs. Libraries are an important part of Avocado
(see definition of what Avocado is) and IMHO denote more value than
the term APIs does.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

And not *on* a given language.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

Documentation Review (v2)

Makefile: require a clean source tree before running local checks

This is just a review followed by minor wording changes and some
heavier formatting changes.

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

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>

Sometimes the local checks, including documentation builds and other
unit and functional tests will fail because of either stale state
or because of external plugins.

Let's require a clean source tree before running local checks to
avoid those false negatives.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

avocado config: Add --paginator to command

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>

Add the --paginator (on|off) option to 'avocado config'.
This option has been missing from that command, which
is inconsistent with the other listing options we have.
Signed-off-by: NLucas Meneghel Rodrigues <lmr@redhat.com>