Merge remote-tracking branch 'ldoktor/docs2'

docs/source/Configuration.rst

@@ -9,7 +9,9 @@ and that's why a configuration system is in place to help with those cases
 The Avocado config file format is based on the (informal)
 `INI file 'specification' <http://en.wikipedia.org/wiki/INI_file>`__, that is implemented by
 Python's  :mod:`ConfigParser`. The format is simple and straightforward, composed by `sections`,
-that contain a number of `keys` and `values`. Take for example a basic Avocado config file::
+that contain a number of `keys` and `values`. Take for example a basic Avocado config file:
+
+.. code-block:: ini
 
     [datadir.paths]
     base_dir = ~/avocado
@@ -50,7 +52,9 @@ Plugin config files
 Plugins can also be configured by config files. In order to not disturb the main Avocado config file, those plugins,
 if they wish so, may install additional config files to ``/etc/avocado/conf.d/[pluginname].conf``, that will be parsed
 after the system wide config file. Users can override those values as well at the local config file level.
-Considering the config for the hypothethical plugin ``salad``::
+Considering the config for the hypothethical plugin ``salad``:
+
+.. code-block:: ini
 
     [salad.core]
     base = ceasar

docs/source/DevelopmentTips.rst

@@ -143,8 +143,8 @@ Create task query:
 #. Press `Finish`.
 #. Trello tasks assigned to you will now appear in the Mylyn Task List.
 
-Noy you can start using tasks by clicking the small bubble in front of the
-name. This closes all editors. Try openning some and then click the bubble
+Note you can start using tasks by clicking the small bubble in front of the
+name. This closes all editors. Try opening some and then click the bubble
 again. They should get closed. When you click the bubble third time, it should
 resume all the open editors from before.
 

docs/source/Diff.rst

@@ -5,7 +5,9 @@ Job Diff
 ========
 
 Avocado Diff plugin allows users to easily compare several aspects of
-two given jobs. The basic usage is::
+two given jobs. The basic usage is:
+
+.. code-block:: diff
 
     $ avocado diff 7025aaba 384b949c
     --- 7025aaba9c2ab8b4bba2e33b64db3824810bb5df
@@ -40,7 +42,9 @@ can also enable/disable those sections with ``--diff-filter``. Please see
 ``avocado diff --help`` for more information.
 
 Jobs can be identified by the Job ID, by the results directory or by the
-key ``latest``. Example::
+key ``latest``. Example:
+
+.. code-block:: diff
 
     $ avocado diff ~/avocado/job-results/job-2016-08-03T15.56-4b3cb5b/ latest
     --- 4b3cb5bbbb2435c91c7b557eebc09997d4a0f544

docs/source/GetStartedGuide.rst

@@ -131,9 +131,10 @@ attempt to do so by running::
 
   pip install -r https://raw.githubusercontent.com/avocado-framework/avocado/master/requirements.txt
 
-The result, though, is highly dependent on your system setup, such as
-having the right compilers, header files and libraries available.  The
-more predictable and complete Avocado experience can be achieved with
+This way you only get the base avocado-framework without the optional
+plugins. Additionally the installation requires correctly configured
+system with the right compilers, header files and libraries available.
+The more predictable and complete Avocado experience can be achieved with
 the official RPM packages.
 
 Using Avocado

docs/source/MaintenanceGuide.rst

@@ -12,7 +12,9 @@ Bump the version number
 =======================
 
 Go through the avocado code base and update the release number. At the time
-of this writing, the diff looked like this::
+of this writing, the diff looked like this:
+
+.. code-block:: diff
 
     diff --git a/avocado.spec b/avocado.spec
     index eb910e8..21313ca 100644

docs/source/Mux.rst

@@ -102,7 +102,9 @@ of parameters.
 
 Let's start with an example (line numbers at the first columns are for
 documentation purposes only, they are not part of the multiplex file
-format)::
+format):
+
+.. code-block:: yaml
 
      1  hw:
      2      cpu: !mux
@@ -181,7 +183,9 @@ Each node can define key/value pairs (lines 4,6,8,11,...). Additionally
 each children node inherits values of it's parent and the result is called
 node ``environment``.
 
-Given the node structure bellow::
+Given the node structure bellow:
+
+.. code-block:: yaml
 
     devtools:
         compiler: 'cc'
@@ -217,7 +221,9 @@ Variants
 --------
 
 In the end all leaves are gathered and turned into parameters, more specifically into
-``AvocadoParams``::
+``AvocadoParams``:
+
+.. code-block:: yaml
 
     setup:
         graphic:
@@ -235,7 +241,9 @@ by path. But the most powerful multiplexer feature is that it can generate
 multiple variants. To do that you need to tag a node whose children are
 ment to be multiplexed. Effectively it returns only leaves of one child at the
 time.In order to generate all possible variants multiplexer creates cartesian
-product of all of these variants::
+product of all of these variants:
+
+.. code-block:: yaml
 
     cpu: !mux
         intel:
@@ -253,7 +261,9 @@ Produces 6 variants::
     /cpu/arm, /fmt/raw
 
 The !mux evaluation is recursive so one variant can expand to multiple
-ones::
+ones:
+
+.. code-block:: yaml
 
     fmt: !mux
         qcow: !mux
@@ -291,7 +301,9 @@ be overridden by ``--mux-path``, which accepts multiple arguments. What it does
 it splits leaves by the provided paths. Each query goes one by one through
 those sub-trees and first one to hit the match returns the result. It might not
 solve all problems, but it can help to combine existing YAML files with your
-ones::
+ones:
+
+.. code-block:: yaml
 
     qa:         # large and complex read-only file, content injected into /qa
         tests:
@@ -325,7 +337,7 @@ are available in the default path and you can safely use ``params.get(key)``.
 
 When you need to put a file into a different location, for example
 when you have two files and you don't want the content to be merged into
-a single place becomming effectively a single blob, you can do that by
+a single place becoming effectively a single blob, you can do that by
 giving a name to your yaml file::
 
     avocado run sleeptest.py --mux-yaml duration:duration.yaml
@@ -353,7 +365,7 @@ intention of the test writer. There are several ways to access the values:
 It's recommended to use the simple injection for single YAML files, relative
 injection for multiple simple YAML files and the last option is for very
 advanced setups when you either can't modify the YAML files and you need to
-specify custom resoltion order or you are specifying non-test parameters, for
+specify custom resolution order or you are specifying non-test parameters, for
 example parameters for your plugin, which you need to separate from the test
 parameters.
 
@@ -363,7 +375,9 @@ Multiple files
 
 You can provide multiple files. In such scenario final tree is a combination
 of the provided files where later nodes with the same name override values of
-the preceding corresponding node. New nodes are appended as new children::
+the preceding corresponding node. New nodes are appended as new children:
+
+.. code-block:: yaml
 
     file-1.yaml:
         debug:
@@ -377,7 +391,9 @@ the preceding corresponding node. New nodes are appended as new children::
         fast:
             CFLAGS: '-Ofast'
 
-results in::
+results in:
+
+.. code-block:: yaml
 
     debug:
         CFLAGS: '-O0 -g'
@@ -387,7 +403,9 @@ results in::
         CFLAGS: '-Ofast'    # appended
 
 It's also possible to include existing file into another a given node in another
-file. This is done by the `!include : $path` directive::
+file. This is done by the `!include : $path` directive:
+
+.. code-block:: yaml
 
     os:
         fedora:
@@ -415,7 +433,9 @@ name and the parsing fails.
 !include
 --------
 
-Includes other file and injects it into the node it's specified in::
+Includes other file and injects it into the node it's specified in:
+
+.. code-block:: yaml
 
     my_other_file:
         !include : other.yaml
@@ -428,7 +448,9 @@ Relative paths start from the original file's directory.
 !using
 ------
 
-Prepends path to the node it's defined in::
+Prepends path to the node it's defined in:
+
+.. code-block:: yaml
 
     !using : /foo
     bar:
@@ -441,7 +463,9 @@ Prepends path to the node it's defined in::
 ------------
 
 Removes node if it existed during the merge. It can be used to extend
-incompatible YAML files::
+incompatible YAML files:
+
+.. code-block:: yaml
 
     os:
         fedora:

docs/source/ResultFormats.rst

@@ -54,6 +54,13 @@ You can also request that the report be opened automatically by using the
 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
 ------------------------
 
@@ -246,7 +253,7 @@ Exit Codes
 
 Avocado exit code tries to represent different things that can happen during
 an execution. That means exit codes can be a combination of codes that were
-ORed toghether as a simgle exit code. The final exit code can be debundled so
+ORed together as a single exit code. The final exit code can be de-bundled so
 users can have a good idea on what happened to the job.
 
 The single individual exit codes are:

docs/source/RunningTestsRemotely.rst

@@ -206,10 +206,11 @@ an image with Avocado, you can run a test inside the container with a
 command similar to::
 
     $ avocado run passtest.py warntest.py failtest.py --docker ldoktor/fedora-avocado --docker-cmd "sudo docker"
-    DOCKER     : Container id '4bcbcd69801211501a0dde5926c0282a9630adbe29ecb17a21ef04f024366943'
     JOB ID     : db309f5daba562235834f97cad5f4458e3fe6e32
     JOB LOG    : $HOME/avocado/job-results/job-2016-07-25T08.01-db309f5/job.log
     TESTS      : 3
+    DOCKER     : Container id '4bcbcd69801211501a0dde5926c0282a9630adbe29ecb17a21ef04f024366943'
+    DOCKER     : Container name 'job-2016-07-25T08.01-db309f5.avocado'
      (1/3) /avocado_remote_test_dir/$HOME/passtest.py:PassTest.test: PASS (0.00 s)
      (2/3) /avocado_remote_test_dir/$HOME/warntest.py:WarnTest.test: WARN (0.00 s)
      (3/3) /avocado_remote_test_dir/$HOME/failtest.py:FailTest.test: FAIL (0.00 s)

docs/source/WritingTests.rst

@@ -82,6 +82,11 @@ Additionally, we'll save a raw copy of the whiteboard contents on a file named
 (maybe you want to use the result of a benchmark directly with your custom made scripts
 to analyze that particular benchmark result).
 
+If you need to attach several output files, you can also use
+``self.outputdir``, which points to the
+``$RESULTS/test-results/$TEST_ID/data`` location and is reserved for
+arbitrary test result data.
+
 Accessing test parameters
 =========================
 
@@ -89,7 +94,9 @@ Each test has a set of parameters that can be accessed through
 ``self.params.get($name, $path=None, $default=None)``.
 Avocado finds and populates ``self.params`` with all parameters you define on
 a Multiplex Config file (see :doc:`Mux`). As an example, consider
-the following multiplex file for sleeptest::
+the following multiplex file for sleeptest:
+
+.. code-block:: yaml
 
     sleeptest:
         type: "builtin"
@@ -438,13 +445,6 @@ location of the test suite code (tarball) through
 decompress the suite tarball, followed by :func:`avocado.utils.build.make`, that will build
 the suite.
 
-The ``setUp`` method is the only place in avocado where you are allowed to
-call the ``skip`` method, given that, if a test started to be executed, by
-definition it can't be skipped anymore. Avocado will do its best to enforce
-this boundary, so that if you use ``skip`` outside ``setUp``, the test upon
-execution will be marked with the ``ERROR`` status, and the error message
-will instruct you to fix your test's code.
-
 In this example, the ``test`` method just gets into the base directory of
 the compiled suite  and executes the ``./synctest`` command, with appropriate
 parameters, using :func:`avocado.utils.process.system`.
@@ -540,7 +540,7 @@ Detailing the ``fetch_asset()`` attributes:
   cache directory, pointing to the file original location.
 * ``expire:`` (optional) time period that the cached file will be considered
   valid. After that period, the file will be dowloaded again. The value can
-  be an integer or a string containig the time and the unit. Example: '10d'
+  be an integer or a string containing the time and the unit. Example: '10d'
   (ten days). Valid units are ``s`` (second), ``m`` (minute), ``h`` (hour) and
   ``d`` (day).
 
@@ -761,7 +761,7 @@ Setting a Test Timeout
 Sometimes your test suite/test might get stuck forever, and this might
 impact your test grid. You can account for that possibility and set up a
 ``timeout`` parameter for your test. The test timeout can be set through
-the multiplex, as shown below. 
+the multiplex, as shown below.
 
 ::
 
@@ -955,6 +955,13 @@ separate process), it doesn't make sense to support unittest's
 instantiated for each test, so it's pointless to run code in those
 methods, since they're supposed to keep class state between tests.
 
+The ``setUp`` method is the only place in avocado where you are allowed to
+call the ``skip`` method, given that, if a test started to be executed, by
+definition it can't be skipped anymore. Avocado will do its best to enforce
+this boundary, so that if you use ``skip`` outside ``setUp``, the test upon
+execution will be marked with the ``ERROR`` status, and the error message
+will instruct you to fix your test's code.
+
 If you require a common setup to a number of tests, the current
 recommended approach is to to write regular :meth:`setUp
 <unittest.TestCase.setUp>` and :meth:`tearDown
@@ -989,7 +996,7 @@ If your test setup is some kind of action that will last accross
 processes, like the installation of a software package given in the
 previous example, you're pretty much covered here.
 
-If you need to keep other type of data a class acrross test
+If you need to keep other type of data a class across test
 executions, you'll have to resort to saving and restoring the data
 from an outside source (say a "pickle" file).  Finding and using a
 reliable and safe location for saving such data is currently not in