Merge pull request #656 from clebergnu/doc_review_3rd_round

Documentation Review (3rd round)

docs/source/ReferenceGuide.rst

@@ -11,15 +11,18 @@ This guide presents information on the Avocado basic design and its internals.
 Job ID
 ======
 
-The Job ID is a SHA1 string that has some information encoded:
+The Job ID is a random SHA1 string that uniquely identifies a given job.
 
-* Hostname
-* ISO timestamp
-* 64 bit integer
+The full form of the SHA1 string is used is most references to a job::
 
-The idea is to have a unique identifier that can be used for job data, for
-the purposes of joining on a single database results obtained by jobs run
-on different systems.
+  $ avocado run sleeptest
+  JOB ID     : 49ec339a6cca73397be21866453985f88713ac34
+  ...
+
+But a shorter version is also used at some places, such as in the job
+results location::
+
+  JOB LOG    : $HOME/avocado/job-results/job-2015-06-10T10.44-49ec339/job.log
 
 .. _test-types:
 
@@ -104,4 +107,121 @@ diagram below shows how Avocado analyzes a file and decides what to do with
 it:
 
 .. figure:: diagram.png
+
+Results Specification
+=====================
+
+On a machine that executed tests, job results are available under
+``[job-results]/job-[timestamp]-[short job ID]``, where ``logdir`` is the configured Avocado
+logs directory (see the data dir plugin), and the directory name includes
+a timestamp, such as ``job-2014-08-12T15.44-565e8de``. A typical
+results directory structure can be seen below ::
+
+    $HOME/avocado/job-results/job-2014-08-13T00.45-4a92bc0/
+    ├── id
+    ├── job.log
+    ├── results.json
+    ├── results.xml
+    ├── sysinfo
+    │   ├── post
+    │   │   ├── brctl_show
+    │   │   ├── cmdline
+    │   │   ├── cpuinfo
+    │   │   ├── current_clocksource
+    │   │   ├── df_-mP
+    │   │   ├── dmesg_-c
+    │   │   ├── dmidecode
+    │   │   ├── fdisk_-l
+    │   │   ├── gcc_--version
+    │   │   ├── hostname
+    │   │   ├── ifconfig_-a
+    │   │   ├── interrupts
+    │   │   ├── ip_link
+    │   │   ├── ld_--version
+    │   │   ├── lscpu
+    │   │   ├── lspci_-vvnn
+    │   │   ├── meminfo
+    │   │   ├── modules
+    │   │   ├── mount
+    │   │   ├── mounts
+    │   │   ├── numactl_--hardware_show
+    │   │   ├── partitions
+    │   │   ├── scaling_governor
+    │   │   ├── uname_-a
+    │   │   ├── uptime
+    │   │   └── version
+    │   └── pre
+    │       ├── brctl_show
+    │       ├── cmdline
+    │       ├── cpuinfo
+    │       ├── current_clocksource
+    │       ├── df_-mP
+    │       ├── dmesg_-c
+    │       ├── dmidecode
+    │       ├── fdisk_-l
+    │       ├── gcc_--version
+    │       ├── hostname
+    │       ├── ifconfig_-a
+    │       ├── interrupts
+    │       ├── ip_link
+    │       ├── ld_--version
+    │       ├── lscpu
+    │       ├── lspci_-vvnn
+    │       ├── meminfo
+    │       ├── modules
+    │       ├── mount
+    │       ├── mounts
+    │       ├── numactl_--hardware_show
+    │       ├── partitions
+    │       ├── scaling_governor
+    │       ├── uname_-a
+    │       ├── uptime
+    │       └── version
+    └── test-results
+        └── tests
+            ├── sleeptest.py.long
+            │   ├── data
+            │   ├── debug.log
+            │   └── sysinfo
+            │       ├── post
+            │       └── pre
+            ├── sleeptest.py.medium
+            │   ├── data
+            │   ├── debug.log
+            │   └── sysinfo
+            │       ├── post
+            │       └── pre
+            └── sleeptest.py.short
+                ├── data
+                ├── debug.log
+                └── sysinfo
+                    ├── post
+                    └── pre
+    
+    20 directories, 59 files
+
+
+From what you can see, the results dir has:
+
+1) A human readable ``id`` in the top level, with the job SHA1.
+2) A human readable ``job.log`` in the top level, with human readable logs of
+   the task
+3) A machine readable ``results.xml`` in the top level, with a summary of the
+   job information in xUnit format.
+4) A top level ``sysinfo`` dir, with sub directories ``pre`` and ``post``, that store
+   sysinfo files pre job and post job, respectively.
+5) Subdirectory ``test-results``, that contains a number of subdirectories
+   (tagged testnames). Those tagged testnames represent instances of test
+   execution results.
+
+Test execution instances specification
+--------------------------------------
+
+The instances should have:
+
+1) A top level human readable ``test.log``, with test debug information
+2) A ``sysinfo`` subdir, with sub directories ``pre`` and ``post``, that store
+   sysinfo files pre test and post test, respectively.
+3) A ``data`` subdir, where the test can output a number of files if necessary.
+
 .. [#f1] Avocado plugins can introduce additional test types.

docs/source/ResultsSpecification.rst

-=====================
-Results Specification
-=====================
-
-On a machine that executed tests, job results are available under
-``[job-results]/job-[timestamp]-[short job ID]``, where ``logdir`` is the configured Avocado
-logs directory (see the data dir plugin), and the directory name includes
-a timestamp, such as ``job-2014-08-12T15.44-565e8de``. A typical
-results directory structure can be seen below ::
-
-    $HOME/avocado/job-results/job-2014-08-13T00.45-4a92bc0/
-    ├── id
-    ├── job.log
-    ├── results.json
-    ├── results.xml
-    ├── sysinfo
-    │   ├── post
-    │   │   ├── brctl_show
-    │   │   ├── cmdline
-    │   │   ├── cpuinfo
-    │   │   ├── current_clocksource
-    │   │   ├── df_-mP
-    │   │   ├── dmesg_-c
-    │   │   ├── dmidecode
-    │   │   ├── fdisk_-l
-    │   │   ├── gcc_--version
-    │   │   ├── hostname
-    │   │   ├── ifconfig_-a
-    │   │   ├── interrupts
-    │   │   ├── ip_link
-    │   │   ├── ld_--version
-    │   │   ├── lscpu
-    │   │   ├── lspci_-vvnn
-    │   │   ├── meminfo
-    │   │   ├── modules
-    │   │   ├── mount
-    │   │   ├── mounts
-    │   │   ├── numactl_--hardware_show
-    │   │   ├── partitions
-    │   │   ├── scaling_governor
-    │   │   ├── uname_-a
-    │   │   ├── uptime
-    │   │   └── version
-    │   └── pre
-    │       ├── brctl_show
-    │       ├── cmdline
-    │       ├── cpuinfo
-    │       ├── current_clocksource
-    │       ├── df_-mP
-    │       ├── dmesg_-c
-    │       ├── dmidecode
-    │       ├── fdisk_-l
-    │       ├── gcc_--version
-    │       ├── hostname
-    │       ├── ifconfig_-a
-    │       ├── interrupts
-    │       ├── ip_link
-    │       ├── ld_--version
-    │       ├── lscpu
-    │       ├── lspci_-vvnn
-    │       ├── meminfo
-    │       ├── modules
-    │       ├── mount
-    │       ├── mounts
-    │       ├── numactl_--hardware_show
-    │       ├── partitions
-    │       ├── scaling_governor
-    │       ├── uname_-a
-    │       ├── uptime
-    │       └── version
-    └── test-results
-        └── tests
-            ├── sleeptest.py.long
-            │   ├── data
-            │   ├── debug.log
-            │   └── sysinfo
-            │       ├── post
-            │       └── pre
-            ├── sleeptest.py.medium
-            │   ├── data
-            │   ├── debug.log
-            │   └── sysinfo
-            │       ├── post
-            │       └── pre
-            └── sleeptest.py.short
-                ├── data
-                ├── debug.log
-                └── sysinfo
-                    ├── post
-                    └── pre
-    
-    20 directories, 59 files
-
-
-From what you can see, the results dir has:
-
-1) A human readable ``id`` in the top level, with the job SHA1.
-2) A human readable ``job.log`` in the top level, with human readable logs of
-   the task
-3) A machine readable ``results.xml`` in the top level, with a summary of the
-   job information in xUnit format.
-4) A top level ``sysinfo`` dir, with sub directories ``pre`` and ``post``, that store
-   sysinfo files pre job and post job, respectively.
-5) Subdirectory ``test-results``, that contains a number of subdirectories
-   (tagged testnames). Those tagged testnames represent instances of test
-   execution results.
-
-Test execution instances specification
-======================================
-
-The instances should have:
-
-1) A top level human readable ``test.log``, with test debug information
-2) A ``sysinfo`` subdir, with sub directories ``pre`` and ``post``, that store
-   sysinfo files pre test and post test, respectively.
-3) A ``data`` subdir, where the test can output a number of files if necessary.

docs/source/WritingTests.rst

@@ -64,7 +64,7 @@ Each test instance provides a so called ``whiteboard``. It that can be accessed
 through ``self.whiteboard``. This whiteboard is simply a string that will be
 automatically saved to test results (as long as the output format supports it).
 If you choose to save binary data to the whiteboard, it's your responsibility to
-encoded it first (base64 is the obvious choice).
+encode it first (base64 is the obvious choice).
 
 Building on the previously demonstrated ``sleeptest``, suppose that you want to save the
 sleep length to be used by some other script or data analysis tool::

docs/source/index.rst

@@ -11,7 +11,6 @@ Contents:
    GetStartedGuide
    WritingTests
    Configuration
-   ResultsSpecification
    MultiplexConfig
    Plugins
    OutputPlugins