Merge branch 'clebergnu-readme_v2'

Signed-off-by: NAmador Pahim <apahim@redhat.com>

README.rst

-Avocado Test Framework
-======================
+========================
+ Avocado Test Framework
+========================
 
-Avocado is a test framework that is built on the experience accumulated with
-`autotest <http://autotest.github.io/>`__, while improving on its weaknesses
-and shortcomings.
+Avocado is a set of tools and libraries to help with automated testing.
 
-The main goal of the Avocado project is to provide a set of smart tools for
-automated testing and continuous integration. Among them, we can highlight:
+One can call it a test framework with benefits.  Native tests are
+written in Python and they follow the unittest
+(https://docs.python.org/2.7/library/unittest.html) pattern, but any
+executable can serve as a test.
 
-- A powerful test runner;
-- A multiplexer that allows tests to be run with different sets of variables;
-- Test APIs for test writers;
-- A database for results, with a web interface;
-- A scheduler for setting up a test grid.
+Avocado is composed of:
 
-Using avocado
--------------
+* A test runner that lets you execute tests. Those tests can be either
+  written in your language of choice, or be written in Python and use
+  the available libraries. In both cases, you get facilities such as
+  automated log and system information collection.
 
-The most straightforward way of `using` avocado is to install packages
-available for your distro:
+* Libraries that help you write tests in a concise, yet expressive and
+  powerful way.  You can find more information about what libraries
+  are intended for test writers at:
+  http://avocado-framework.readthedocs.io/en/latest/api/utils/avocado.utils.html
 
-1) Fedora/RHEL
+* Plugins that can extend and add new functionality to the Avocado
+  Framework.  More info at:
+  http://avocado-framework.readthedocs.io/en/latest/Plugins.html
 
-   Avocado is not yet officially packed in Fedora/RHEL, but you can use avocado
-   yum repositories by putting corresponding file into ``/etc/yum.repos.d``.
+Avocado is built on the experience accumulated with Autotest
+(http://autotest.github.io), while improving on its weaknesses and
+shortcomings.
 
-   *  `Fedora repo <https://repos-avocadoproject.rhcloud.com/static/avocado-fedora.repo>`__
-   *  `RHEL repo <https://repos-avocadoproject.rhcloud.com/static/avocado-el.repo>`__
+Installing Avocado
+==================
 
-   and install it by ``yum install avocado`` (or using ``dnf``)
+Installing from Packages
+------------------------
 
-Once you install it, you can start exploring it by checking the output of
-``avocado --help`` and the test runner man-page, accessible via ``man avocado``.
+Fedora
+~~~~~~
 
-If you want to `develop` avocado, or run it directly from the git repository,
-you have a couple of options:
+Avocado is available in stock Fedora 24 and later.  The main package
+name is ``python-avocado``, and can be installed with::
 
-1) The avocado test runner was designed to run in tree, for rapid development
-   prototypes. After running::
+    dnf install python-avocado
 
-    $ make develop
+Other available packages (depending on the Avocado version) may include:
 
-   Just use::
+* ``python-avocado-examples``: contains example tests and other example files
+* ``python2-avocado-plugins-output-html``: HTML job report plugin
+* ``python2-avocado-plugins-runner-remote``: execution of jobs on a remote machine
+* ``python2-avocado-plugins-runner-vm``: execution of jobs on a libvirt based VM
+* ``python2-avocado-plugins-runner-docker``: execution of jobs on a Docker container
 
-    $ scripts/avocado --help
+Fedora from Avocado's own Repo
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-2) Installing avocado in the system is also an option, although remember that
-   distutils has no ``uninstall`` functionality::
+The Avocado project also makes the latest release, and the LTS (Long
+Term Stability) releases available from its own package repository.
+To use it, first get the package repositories configuration file by
+running the following command::
 
-    $ sudo python setup.py install
-    $ avocado --help
+    sudo curl https://repos-avocadoproject.rhcloud.com/static/avocado-fedora.repo -o /etc/yum.repos.d/avocado.repo
+
+Now check if you have the ``avocado`` and ``avocado-lts`` repositories configured by running::
+
+    sudo dnf repolist avocado avocado-lts
+    ...
+    repo id      repo name                          status
+    avocado      Avocado                            50
+    avocado-lts  Avocado LTS (Long Term Stability)  disabled
+
+Regular users of Avocado will want to use the standard ``avocado``
+repository, which tracks the latest Avocado releases.  For more
+information about the LTS releases, please refer to the Avocado Long
+Term Stability thread
+(https://www.redhat.com/archives/avocado-devel/2016-April/msg00038.html)
+and to your package management docs on how to switch to the
+``avocado-lts`` repo.
+
+Finally, after deciding between regular Avocado releases or LTS, you
+can install the RPM packages by running the following commands::
+
+    dnf install python-avocado
+
+Additionally, other Avocado packages are available for Fedora:
+
+* ``python-avocado-examples``: contains example tests and other example files
+* ``python2-avocado-plugins-output-html``: HTML job report plugin
+* ``python2-avocado-plugins-runner-remote``: execution of jobs on a remote machine
+* ``python2-avocado-plugins-runner-vm``: execution of jobs on a libvirt based VM
+* ``python2-avocado-plugins-runner-docker``: execution of jobs on a Docker container
+
+Enterprise Linux
+~~~~~~~~~~~~~~~~
+
+Avocado packages for Enterprise Linux are available from the Avocado
+project RPM repository.  Additionally, some packages from the EPEL repo are
+necessary, so you need to enable it first.  For EL7, running the
+following command should do it::
+
+    yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
+
+Then you must use the Avocado project RHEL repo
+(https://repos-avocadoproject.rhcloud.com/static/avocado-el.repo).
+Running the following command should give you the basic Avocado
+installation ready::
+
+    curl https://repos-avocadoproject.rhcloud.com/static/avocado-el.repo -o /etc/yum.repos.d/avocado.repo
+    yum install python-avocado
+
+Other available packages (depending on the Avocado version) may include:
+
+* ``python-avocado-examples``: contains example tests and other example files
+* ``python2-avocado-plugins-output-html``: HTML job report plugin
+* ``python2-avocado-plugins-runner-remote``: execution of jobs on a remote machine
+* ``python2-avocado-plugins-runner-vm``: execution of jobs on a libvirt based VM
+* ``python2-avocado-plugins-runner-docker``: execution of jobs on a Docker container
+
+The LTS (Long Term Stability) repositories are also available for
+Enterprise Linux.  For more information about the LTS releases, please
+refer to the Avocado Long Term Stability thread
+(https://www.redhat.com/archives/avocado-devel/2016-April/msg00038.html)
+and to your package management docs on how to switch to the
+``avocado-lts`` repo.
+
+OpenSUSE
+~~~~~~~~
+
+The OpenSUSE project packages LTS versions of Avocado
+(https://build.opensuse.org/package/show/Virtualization:Tests/avocado).
+You can install packages by running the following commands::
+
+  zypper install avocado
+
+Debian
+~~~~~~
+
+DEB package support is available in the source tree (look at the
+``contrib/packages/debian`` directory.  No actual packages are
+provided by the Avocado project or the Debian repos.
+
+
+Setting up a Development Environment
+====================================
+
+If you want to develop Avocado, or just run it directly from the GIT
+repository, fetch the source code and run::
+
+  make develop
+
+From this point on, running ``avocado`` should load everything from
+your current source code checkout.
+
+Brief Usage Instructions
+========================
+
+To list available tests, call the ``list`` subcommand.  For example::
+
+  avocado list
+
+  INSTRUMENTED <examples_path>/tests/abort.py:AbortTest.test
+  INSTRUMENTED <examples_path>/tests/canceltest.py:CancelTest.test
+  ...
+  SIMPLE       <examples_path>/tests/passtest.sh
+
+To run a test, call the ``run`` command::
+
+  avocado run <examples_path>/tests/passtest.sh
+  JOB ID     : <id>
+  JOB LOG    : <job-results>/job-<date>-<shortid>/job.log
+  (1/1) <examples_path>/tests/passtest.sh: PASS (0.04 s)
+  RESULTS    : PASS 1 | ERROR 0 | FAIL 0 | SKIP 0 | WARN 0 | INTERRUPT 0 | CANCEL 0
+  TESTS TIME : 0.04 s
+
+To continue exploring Avocado, check out the output of ``avocado --help``
+and the test runner man-page, accessible via ``man avocado``.
 
 Documentation
--------------
+=============
 
 Avocado comes with in tree documentation about the most advanced features and
 its API. It can be built with ``sphinx``, but a publicly available build of

docs/source/GetStartedGuide.rst

@@ -6,26 +6,41 @@ Getting Started
 
 The first step towards using Avocado is, quite obviously, installing it.
 
+.. Note: this section section shares content with the project README
+         file.  When editing this section, also sync the content with
+         the README file.  Also notice that this file uses a larger
+         set of ReST/sphinx statements, which do not look as good on a
+         plain README file.
+
 Installing Avocado
 ==================
 
 Installing from Packages
 ------------------------
 
-Avocado is officially available in RPM packages for Fedora and
-Enterprise Linux.  Other RPM based distributions may package and ship
-Avocado themselves.  DEB package support is available in the source
-tree (look at the ``contrib/packages/debian`` directory).
+Fedora
+~~~~~~
+
+Avocado is available in stock Fedora 24 and later.  The main package
+name is ``python-avocado``, and can be installed with::
 
-.. Note: the following text should instead reference the distro tiers levels
+    dnf install python-avocado
 
-Avocado is primarily being developed on Fedora, but reasonable efforts
-are being made to support other GNU/Linux based platforms.
+Other available packages (depending on the Avocado version) may include:
 
-Fedora
-~~~~~~
+* ``python-avocado-examples``: contains example tests and other example files
+* ``python2-avocado-plugins-output-html``: HTML job report plugin
+* ``python2-avocado-plugins-runner-remote``: execution of jobs on a remote machine
+* ``python2-avocado-plugins-runner-vm``: execution of jobs on a libvirt based VM
+* ``python2-avocado-plugins-runner-docker``: execution of jobs on a Docker container
 
-First, get the package repositories configuration file by running the following command::
+Fedora from Avocado's own Repo
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Avocado project also makes the latest release, and the LTS (Long
+Term Stability) releases available from its own package repository.
+To use it, first get the package repositories configuration file by
+running the following command::
 
     sudo curl https://repos-avocadoproject.rhcloud.com/static/avocado-fedora.repo -o /etc/yum.repos.d/avocado.repo
 
@@ -46,36 +61,41 @@ how to switch to the ``avocado-lts`` repo.
 Finally, after deciding between regular Avocado releases or LTS, you
 can install the RPM packages by running the following commands::
 
-    sudo dnf install avocado
+    dnf install python-avocado
 
 Additionally, other Avocado packages are available for Fedora:
 
- * ``avocado-examples``: contains example tests and other example files
- * ``avocado-plugins-output-html``: HTML job report plugin
- * ``avocado-plugins-runner-remote``: execution of jobs on a remote machine
- * ``avocado-plugins-runner-vm``: execution of jobs on a libvirt based VM
- * ``avocado-plugins-runner-docker``: execution of jobs on a Docker container
+* ``python-avocado-examples``: contains example tests and other example files
+* ``python2-avocado-plugins-output-html``: HTML job report plugin
+* ``python2-avocado-plugins-runner-remote``: execution of jobs on a remote machine
+* ``python2-avocado-plugins-runner-vm``: execution of jobs on a libvirt based VM
+* ``python2-avocado-plugins-runner-docker``: execution of jobs on a Docker container
 
 Enterprise Linux
 ~~~~~~~~~~~~~~~~
 
-If you're running either Red Hat Enterprise Linux or one of the derivatives
-such as CentOS, just adapt to the following URL and commands::
+Avocado packages for Enterprise Linux are available from the Avocado
+project RPM repository.  Additionally, some packages from the EPEL repo are
+necessary, so you need to enable it first.  For EL7, running the
+following command should do it::
+
+    yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
+
+Then you must use the Avocado project RHEL repo
+(https://repos-avocadoproject.rhcloud.com/static/avocado-el.repo).
+Running the following command should give you the basic Avocado
+installation ready::
 
-    # If not already, enable epel (for RHEL7 it's following cmd)
-    sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
-    # Add avocado repository and install avocado
-    sudo curl https://repos-avocadoproject.rhcloud.com/static/avocado-el.repo -o /etc/yum.repos.d/avocado.repo
-    sudo yum install avocado
+    curl https://repos-avocadoproject.rhcloud.com/static/avocado-el.repo -o /etc/yum.repos.d/avocado.repo
+    yum install python-avocado
 
-As with Fedora, other Avocado packages are available for Enterprise
-Linux:
+Other available packages (depending on the Avocado version) may include:
 
- * ``avocado-examples``: contains example tests and other example files
- * ``avocado-plugins-output-html``: HTML job report plugin
- * ``avocado-plugins-runner-remote``: execution of jobs on a remote machine
- * ``avocado-plugins-runner-vm``: execution of jobs on a libvirt based VM
- * ``avocado-plugins-runner-docker``: execution of jobs on a Docker container
+* ``python-avocado-examples``: contains example tests and other example files
+* ``python2-avocado-plugins-output-html``: HTML job report plugin
+* ``python2-avocado-plugins-runner-remote``: execution of jobs on a remote machine
+* ``python2-avocado-plugins-runner-vm``: execution of jobs on a libvirt based VM
+* ``python2-avocado-plugins-runner-docker``: execution of jobs on a Docker container
 
 The LTS (Long Term Stability) repositories are also available for
 Enterprise Linux.  Please refer to the `Avocado Long Term
@@ -90,6 +110,13 @@ install packages by running the following commands::
 
   sudo zypper install avocado
 
+Debian
+~~~~~~
+
+DEB package support is available in the source tree (look at the
+``contrib/packages/debian`` directory.  No actual packages are
+provided by the Avocado project or the Debian repos.
+
 Generic installation from a GIT repository
 ------------------------------------------
 

docs/source/Introduction.rst

 .. _about-avocado:
 
+.. Note: this section section shares content with the project README
+         file.  When editing this section, also sync the content with
+         the README file.  Also notice that this file uses a larger
+         set of ReST/sphinx statements, which do not look as good on a
+         plain README file.
+
 About Avocado
 =============
 
 Avocado is a set of tools and libraries to help with automated testing.
 
-One can call it a test framework with benefits. Native tests are
+One can call it a test framework with benefits.  Native tests are
 written in Python and they follow the :mod:`unittest` pattern, but any
 executable can serve as a test.
 
 Avocado is composed of:
 
-* A test runner that lets you execute tests. Those tests can be either written in your
-  language of choice, or be written in Python and use the available libraries. In both
-  cases, you get facilities such as automated log and system information collection.
+* A test runner that lets you execute tests. Those tests can be either
+  written in your language of choice, or be written in Python and use
+  the available libraries. In both cases, you get facilities such as
+  automated log and system information collection.
 
-* Libraries that help you write tests in a concise, yet expressive and powerful way.
-  You can find more information about what libraries are intended for test writers
-  at :ref:`libraries-apis`.
+* Libraries that help you write tests in a concise, yet expressive and
+  powerful way.  You can find more information about what libraries
+  are intended for test writers at :ref:`libraries-apis`.
 
 * :mod:`Plugins <avocado.plugins>` that can extend and add new functionality
   to the Avocado Framework.
 
+Avocado is built on the experience accumulated with `Autotest
+<http://autotest.github.io/>`__, while improving on its weaknesses and
+shortcomings.
+
 Avocado tries as much as possible to comply with standard Python testing
 technology. Tests written using the Avocado API are derived from the unittest
 class, while other methods suited to functional and performance testing were
@@ -29,6 +40,3 @@ added. The test runner is designed to help people to run their tests while
 providing an assortment of system and logging facilities, with no effort,
 and if you want more features, then you can start using the API features
 progressively.
-
-Mindmap from workshop (2015) demonstrating features on examples
-available `here <https://www.mindmeister.com/504616310>`__.

docs/source/OtherResources.rst

+Other Resources
+===============
+
+This is a collection of some other varied Avocado related sources on
+the web:
+
+* Mindmap from 2015 workshop demonstrating features and examples
+  are available `here <https://www.mindmeister.com/504616310>`__.
+

docs/source/index.rst

@@ -34,6 +34,7 @@ Advanced Topics and Maintenance
    ContributionGuide
    DevelopmentTips
    MaintenanceGuide
+   OtherResources
 
 .. _api-reference: