Merge remote-tracking branch 'ldoktor/docs2'

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

docs/source/Configuration.rst

@@ -14,9 +14,9 @@ that contain a number of `keys` and `values`. Take for example a basic Avocado c
 .. code-block:: ini
 
     [datadir.paths]
-    base_dir = ~/avocado
-    test_dir = /$HOME/Code/avocado/examples/tests
-    data_dir = /usr/share/avocado/data
+    base_dir = /var/lib/avocado
+    test_dir = /usr/share/avocado/tests
+    data_dir = /var/lib/avocado/data
     logs_dir = ~/avocado/job-results
 
 The ``datadir.paths`` section contains a number of keys, all of them related to directories used by
@@ -105,9 +105,9 @@ configuration, after all the files are parsed in their correct resolution order.
         $HOME/.config/avocado/avocado.conf
 
         Section.Key     Value
-        runner.base_dir /usr/share/avocado
-        runner.test_dir $HOME/Code/avocado/examples/tests
-        runner.data_dir /usr/share/avocado/data
+        runner.base_dir /var/lib/avocado
+        runner.test_dir /usr/share/avocado/tests
+        runner.data_dir /var/lib/avocado/data
         runner.logs_dir ~/avocado/job-results
 
 The command also shows the order in which your config files were parsed, giving you a better understanding of
@@ -151,7 +151,7 @@ provided, it will fall back to (we hope) reasonable defaults, and we
 notify the user about that in the output of the command.
 
 The relevant API documentation and meaning of each of those data directories
-is in :mod:`avocado.data_dir`, so it's highly recommended you take a look.
+is in :mod:`avocado.core.data_dir`, so it's highly recommended you take a look.
 
 You may set your preferred data dirs by setting them in the Avocado config files.
 The only exception for important data dirs here is the Avocado tmp dir, used to

docs/source/ResultFormats.rst

@@ -6,6 +6,9 @@ Result Formats
 A test runner must provide an assortment of ways to clearly communicate results
 to interested parties, be them humans or machines.
 
+.. note:: There are several optional result plugins, you can find them in
+   :ref:`result-plugins`.
+
 Results for human beings
 ------------------------
 
@@ -34,32 +37,6 @@ that is, the job and its test(s) results are constantly updated::
 The most important thing is to remember that programs should never need to parse
 human output to figure out what happened to a test job run.
 
-HTML report
-~~~~~~~~~~~
-
-As can be seen in the previous example, Avocado shows the path to an HTML
-report that will be generated as soon as the job finishes running::
-
-    $ avocado run sleeptest.py failtest.py synctest.py
-    ...
-    JOB HTML  : $HOME/avocado/job-results/job-2014-08-12T15.57-5ffe4792/html/results.html
-    ...
-
-You can also request that the report be opened automatically by using the
-``--open-browser`` option. For example::
-
-    $ avocado run sleeptest --open-browser
-
-Will show you the nice looking HTML results report right after ``sleeptest``
-finishes running.
-
-.. warning:: The HTML output is an optional plugin and has to be installed
-             separately as ``avocado-plugins-output-html`` RPM or by executing
-             ``cd optional_plugins/html && python setup.py install``
-             from avocado sources. Note it's enabled by default when using
-             avocado from sorces by ``make develop`` or ``make link``.
-
-
 Machine readable results
 ------------------------
 
@@ -121,6 +98,7 @@ plugin::
 
     $ avocado run sleeptest.py failtest.py synctest.py --json -
     {
+        "cancel": 0,
         "debuglog": "/home/cleber/avocado/job-results/job-2016-08-09T13.53-10715c4/job.log",
         "errors": 0,
         "failures": 1,
@@ -197,8 +175,9 @@ Provides the basic `TAP <http://testanything.org/>`__ (Test Anything Protocol) r
 Silent result
 ~~~~~~~~~~~~~
 
-While not a very fancy result format, an application may want nothing but
-the exit status code from an Avocado test job run. Example::
+This result disables all stdout logging (while keeping the error messages
+being printed to stderr). One can then use the return code to learn about
+the result::
 
     $ avocado --silent run failtest.py
     $ echo $?

docs/source/RunningTestsRemotely.rst

@@ -50,7 +50,7 @@ Optionally, you may have password less SSH login on your remote machine enabled.
 Running your test
 -----------------
 
-Once the remote machine is properly setup, you may run your test. Example::
+Once the remote machine is properly set, you may run your test. Example::
 
     $ scripts/avocado run --remote-hostname 192.168.122.30 --remote-username fedora examples/tests/sleeptest.py examples/tests/failtest.py
     REMOTE LOGIN  : fedora@192.168.122.30:22
@@ -63,7 +63,7 @@ Once the remote machine is properly setup, you may run your test. Example::
 
 A bit of extra logging information is added to your job summary, mainly
 to distinguish the regular execution from the remote one. Note here that
-we did not need `--remote-password` because an SSH key was already setup.
+we did not need `--remote-password` because an SSH key was already set.
 
 Running Tests on a Virtual Machine
 ==================================
@@ -126,7 +126,7 @@ Optionally, you may have password less SSH login on your VM enabled.
 Running your test
 -----------------
 
-Once the virtual machine is properly setup, you may run your test. Example::
+Once the virtual machine is properly set, you may run your test. Example::
 
     $ scripts/avocado run --vm-domain fedora20 --vm-username autotest --vm examples/tests/sleeptest.py examples/tests/failtest.py
     VM DOMAIN : fedora20
@@ -140,7 +140,7 @@ Once the virtual machine is properly setup, you may run your test. Example::
 
 A bit of extra logging information is added to your job summary, mainly
 to distinguish the regular execution from the remote one. Note here that
-we did not need `--vm-password` because the SSH key is already setup.
+we did not need `--vm-password` because the SSH key is already set.
 
 Running Tests on a Docker container
 ===================================
@@ -199,7 +199,7 @@ container::
 Running your test
 -----------------
 
-Assuming your system is properly setup to run Docker, including having
+Assuming your system is properly set to run Docker, including having
 an image with Avocado, you can run a test inside the container with a
 command similar to::
 

docs/source/TestParameters.rst

@@ -7,11 +7,6 @@ Test parameters
    basics, see :ref:`accessing-test-parameters` or practical view by examples
    in `Yaml_to_mux plugin`_.
 
-.. warning:: The multiplexer is under heavy refactor and some of the APIs
-   might still change in the following months (written on 2016-01-22),
-   then we'll do our best to keep the public interfaces as stable as
-   possible.
-
 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

docs/source/index.rst

@@ -28,7 +28,7 @@ Optional Plugins
 ================
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    optional_plugins/index
 

docs/source/optional_plugins/index.rst

@@ -9,4 +9,4 @@ The following pages are the documentation for the optical plugins:
 .. toctree::
    :maxdepth: 1
 
-   resultsdb
+   results.rst

docs/source/optional_plugins/resultsdb.rst → docs/source/optional_plugins/results.rst

-================
+.. _result-plugins:
+
+==============
+Result plugins
+==============
+
+Optional plugins providing various types of job results.
+
+
+HTML results Plugin
+===================
+
+This optional plugin creates beautiful human readable results.
+
+To install the HTML plugin from pip, use::
+
+    pip install avocado-framework-plugin-result-html
+
+Once installed it produces the results in job results dir::
+
+    $ avocado run sleeptest.py failtest.py synctest.py
+    ...
+    JOB HTML  : /home/medic/avocado/job-results/job-2014-08-12T15.57-5ffe4792/html/results.html
+    ...
+
+
+This can be disabled via --html-job-result on|off. One can also
+specify a custom location via --html . Last but not least
+--open-browser can be used to start browser automatically once
+the job finishes.
+
+
 ResultsDB Plugin
 ================
 
@@ -17,7 +48,7 @@ Optionally, you can provide the URL where the Avocado logs are published::
 
     avocado run passtest.py --resultsdb-api http://resultsdb.example.com/api/v2.0/ --resultsdb-logs http://avocadologs.example.com/
 
-The ``--resultsdb-logs`` is a convenience option that will create links
+The --resultsdb-logs is a convenience option that will create links
 to the logs in the ResultsDB records. The links will then have the
 following formats:
 
@@ -35,6 +66,6 @@ You can also set the ResultsDB API URL and logs URL using a config file::
     api_url = http://resultsdb.example.com/api/v2.0/
     logs_url = http://avocadologs.example.com/
 
-And then run the Avocado command without the ``--resultsdb-api`` and
-``--resultsdb-logs`` options. Notice that the command line options will
+And then run the Avocado command without the --resultsdb-api and
+--resultsdb-logs options. Notice that the command line options will
 have precedence over the configuration file.